Using the Bulk Loader Program

 

This topic includes the following sections:

• Defining Bulk Loader Data Files

• Running the Bulk Loader

• Troubleshooting

As a systems administrator, you may have an existing BEA Tuxedo application with multiple BEA Tuxedo services. Manually creating these definitions in the Jolt Repository database may take a long time to complete. The Jolt Bulk Loader is a command utility that allows you to load multiple, previously defined BEA Tuxedo services to the Jolt Repository database in a single step. Using the jbld program, the Bulk Loader utility reads the BEA Tuxedo service definitions from a text file (that you create according to a specific format) and loads them into the Jolt Repository. The service definitions are loaded to the Repository database in one bulk load. After the services populate the Jolt Repository, you can create, edit, and group services using the Jolt Repository Editor.

Note: In order to use the Bulk Loader to add service definitions, you must first configure the Jolt Servers (JSL and JSHs). If you want to use this tool across a firewall, you must also configure Jolt Internet Relay. For configuration instructions, see Configuring JET for Client Access.

 

---

Defining Bulk Loader Data Files

This topic includes the following sections:

• About Bulk Loader Data Files

• Guidelines for Using Keywords

• Keyword Order in the Bulk Loader Data File

• Using Service-level Keywords and Values

• Sample Bulk Loader Data File

About Bulk Loader Data Files

The bulk loader data file is a text file that defines BEA Tuxedo services and their associated parameters. You create this text file (using a text editor) in accordance with the syntax rules described later in this topic.

The Bulk Loader loads the services defined in the bulk loader data file into the Jolt Repository using the package name BULKPKG by default. The -p command overrides the default and you can give the package any name you choose. If another load is performed from a bulk loader data file with the same -p option, all the services in the original package are deleted and a new package is created with the services from the new bulk loader data file.

If a service exists in a package other than the package you name that uses the -p option, the Bulk Loader reports the conflict and does not load a service from the bulk loader Data file into the Repository. Use the Jolt Repository Editor to remove duplicate services and load the bulk loader Data file again. See Using the BEA Jolt Repository Editor for additional information.

Each service definition consists of service properties and parameters that have a set number of parameter properties. Each property is represented by a keyword and a value. Keywords are divided into two levels:

• Service-level

• Parameter-level

Guidelines for Using Keywords

The jbld program reads the service definitions from a text file. To use the keywords, observe the guidelines in Table 4-1.

Table 4-1 Guidelines for Using Keywords

Guideline	Example
Each keyword must be followed by an equal sign (=) and the value	Correct: type=string Incorrect: type
Only one keyword is allowed on each line	Correct: type=string Incorrect: type=string access=out
Any lines not having an equal sign (=) are ignored	Correct: type=string Incorrect: type string
Certain keywords only accept a well-defined set of values	The keyword access accepts only these values: in, out, inout, noaccess
The input file can contain multiple service definitions	service=INQUIRY <service keywords and values> service=DEPOSIT <service keywords and values> service=WITHDRAWAL <service keywords and values> service=TRANSFER <service keywords and values>
Each service definition consists of multiple keywords and values	service=DEPOSIT export=true inbuf=VIEW32 outbuf=VIEW32 inview=INVIEW outview=OUTVIEW

Keyword Order in the Bulk Loader Data File

Keyword order must be maintained within the data files to ensure an error-free transfer during the bulk load.

The first keyword definition in the bulk loader data text file must be the initial service=<NAME> keyword definition (shown in Listing 4-1). Following the service=<NAME> keyword, all remaining service keywords that apply to the named service must be specified before the first param=<NAME> definition. These remaining service keywords can be in any order.

All parameters associated with the service must be specified. Following each param=<NAME> keywords are all the parameter keywords that apply to the named parameter until the next occurrence of a parameter definition. These remaining parameter keywords can be in any order. When all the parameters associated with the first service are defined, specify a new service=<NAME> keyword definition.

Listing 4-1 Keyword Hierarchical Order in a Data File

---

service=<NAME>
<service keyword>=<value>
<service keyword>=<value>
<service keyword>=<value>
param=<NAME>
<parameter keyword>=<value>
<parameter keyword>=<value>
param=<NAME>
<parameter keyword>=<value>
<parameter keyword>=<value>

---

Using Service-level Keywords and Values

A service definition must begin with the service=<NAME> keyword. Services using CARRAY or STRING buffer types should only have one parameter in the service. The recommended parameter name for a service that uses a CARRAY buffer type is CARRAY with carray as the data type. For a service that uses a STRING buffer type, the recommended parameter name is STRING with string as the data type.

Table 4-2 describes the guidelines for use of the service-level keywords and acceptable values for each.

Table 4-2 Service-level Keywords and Values

Keyword	Value
service	Any BEA Tuxedo service name.
export	Either true or false (default is false).
inbuf/outbuf	Select one of these buffer types: FML FML32 VIEW VIEW32 STRING CARRAY X_OCTET X_COMMON X_C_TYPE For more information, see Using BEA Tuxedo Buffer Types with JET.
inview	Any view name for input parameters. (This keyword is optional only if one of the following buffer types is used: VIEW, VIEW32, X_COMMON, X_C_TYPE.)
outview	Any view name for output parameters. (Optional)

Using Parameter-level Keywords and Values

A parameter begins with the param=<NAME> keyword followed by a number of parameter keywords. It ends when another param or service keyword, or end-of-file is encountered. The parameters can be in any order after the param=<NAME> keyword.

Table 4-3 contains the guidelines for use of the parameter-level keywords and acceptable values for each.

Table 4-3 Parameter-level Keywords and Values

Keyword	Values
param	Any parameter name.
type	byte short integer float double string carray
access	in out inout noaccess
count	Maximum number of occurrences (default is 1). The value for unlimited occurrences is 0. Used only by the Jolt Repository Editor to format test screens.

Sample Bulk Loader Data File

Listing 4-2 contains a sample data file in the correct format using the UNIX command cat servicefile. This sample loads TRANSFER, LOGIN, and PAYROLL service definitions to the BULKPKG.

Listing 4-2 Sample Bulk Loader Data File

---

service=TRANSFER
export=true
inbuf=FML
outbuf=FML
param=ACCOUNT_ID
type=integer
access=in
count=2
param=SAMOUNT
type=string
access=in
param=SBALANCE
type=string
access=out
count=2
param=STATLIN
type=string
access=out

service=LOGIN
inbuf=VIEW
inview=LOGINS
outview=LOGINR
export=true
param=user
type=string
access=in
param=passwd
type=string
access=in
param=token
type=integer
access=out

service=PAYROLL
inbuf=FML
outbuf=FML
param=EMPLOYEE_NUM
type=integer
access=in
param=SALARY
type=float
access=inout
param=HIRE_DATE
type=string
access=inout

---

 

---

Running the Bulk Loader

The jbld program is a Java application. Before running the jbld command, set the CLASSPATH environment variable (or its equivalent) to point to the directory where the Jolt class directory (that is, jolt.jar and joltadmin.jar) is located. If the CLASSPATH variable is not set, the Java Virtual Machine (JVM) cannot locate any JET classes.

Note: If the m3.jar file is already specified in the CLASSPATH, then the directory containing the jolt.jar and joltadmin.jar files must be specified ahead of the directory containing the m3.jar file.

The Bulk Loader utility gets its input from command-line arguments and from the input file. For security reasons, jbld does not use command-line arguments to specify user authentication information (user password or application password). Depending on the server's security level, jbld automatically prompts the user for passwords.

To run the Bulk Loader:

1. Type the following at the prompt (with the correct options):

   java bea.jolt.admin.jbld [-n][-p package][-u usrname][-r usrrole] //host:port filename

2. Use the command-line options described in Table 4-4.

   Table 4-4 Bulk Loader Command-line Options

   Option	Description
   -u usrname	Specifies the username (default is your account name). (Mandatory, if required by security)
   -r usrrole	Specifies the user role (default is admin). (Mandatory, if required by security)
   -n	Validates input file against the current Repository; no updates are made to the Repository. (Optional)
   -p package	Repository package name (default is BULKPKG).
   //host:port	Specifies the JRLY or JSL address (host name and IP port number). (Mandatory)
   filename	Specifies the file containing the service definitions. (Mandatory)

 

---

Troubleshooting

See Table 4-5 if you encounter problems using the Bulk Loader utility.

Table 4-5 Bulk Loader Troubleshooting Table

If . . .	Then . . .
The data file is not found	Check to ensure that the path is correct
The keyword is invalid	Check to ensure that the keyword is valid for the package, service, or parameter
The value of the keyword is null	Type a value for the keyword
The value is invalid	Check to ensure that the value of a parameter is within the allocated range for that parameter
The data type is invalid	Check to ensure that the parameter is using a valid data type