Batches are made of batch steps. The script is one of the components of a batch step. The other components of a batch step are the execution target, the authentication credential, and the success code set. For more information, see Components of a Batch Step.
You can create scripts either manually, or use the SmartGuides, notebooks, and windows in the Control Center to create the scripts and save them to the Script Center. If the scripts that you want are in the Script Center, you can import them into the group batches of an application version by using the Change Level notebook. If you are creating or editing a fix or an unassigned batch, use the Create Batch or Edit Batch windows. For more information, refer to the online help for the Satellite Administration Center.
Some scripts that are used in group batches must be parameterized. The parameterization is either to take into account differences between satellites that belong to the same group, or to identify values that may be independent of the satellite that is synchronizing. Parameterizing a script means adding an embedded marker into a script that will be replaced with an attribute when the satellite synchronizes. For more information, see Parameterizing Scripts.
A batch step is the combination of a script, an execution target, authentication credentials, and a success code set.
For scripts that execute against DB2 instances or DB2 databases, all the commands or statements in the script must execute against a single target. For example, if the script has a target of a DB2 instance called test, all of the commands in the script will be executed against test. Similarly, if the target is a DB2 database called payroll, all of the commands and SQL statements in the script will be executed against payroll.
When you specify a DB2 command and its target is either a DB2 instance or a DB2 database, you do not have to specify the DB2 command prefix, nor to you have to explicitly attach to the instance or connect to the database within the script. The instance attachment or database connection is automatically performed based on the target that is specified for the script. For example, to list the tables of a target DB2 database, the script would contain the following DB2 command:
LIST TABLES;
Operating system scripts can contain commands that execute against the operating system, as well as DB2 commands that execute against instances or databases.
Notes:
If you want to include DB2 commands that execute against instances or databases in an operating system script, ensure that the script includes the command to explicitly attach to an instance or connect to a database before the DB2 command or SQL statement is executed. This will ensure that the DB2 command or SQL statement in the script is executed against the intended target instead of the default instance or database. Also, you must use the DB2 prefix with the command. For example, to list the tables of a DB2 database, the operating system script would contain the following DB2 commands:
DB2 CONNECT TO DATABASE test; DB2 LIST TABLES; DB2 CONNECT RESET;
The execution target defines how the script is launched, so the script cannot be associated with more than one target. For example, an instance attach (using authentication credentials) will be initiated before a script with an execution target type of instance is executed.
| Note: | If the target of a script is a DB2 instance, an ATTACH statement will be automatically issued to the instance before the script is executed. A DETACH statement is automatically issued when execution is complete. Similarly, if the target is a DB2 database, a CONNECT statement will be automatically issued to the database before the script is executed. When the execution is complete, a CONNECT RESET statement is automatically issued. This means that all DB2 instances and DB2 databases that are targets of scripts must be cataloged at the satellite, regardless of whether they are local or remote to the satellite. |
In the case of operating system scripts, the entire script is executed to completion, then the exit code or return code is compared with the associated success code set. If successful, the next batch step is executed. Otherwise, execution of the batch is terminated, subsequent steps in the batch are not executed, and an error is reported to the DB2 control server. After the error is reported, synchronization stops, and no additional batches or batch steps are executed. The satellite is disabled from synchronizing and marked as FAILED at the DB2 control server. The satellite cannot synchronize again until you fix it.
Within an operating system script, you can execute both database manager and database commands. You must include the appropriate ATTACH or CONNECT statement to ensure that the command is executed against the correct DB2 instance or DB2 database. You must also include the DETACH or CONNECT RESET statement after the command. Even if the operating system script contains DB2 commands and SQL statements, the entire script is executed to completion before the exit code or return code is compared to the associated success code set. In this situation, you will probably want to use a scripting language (for example, Perl) to check the SQLCODE for each DB2 command or SQL statement that you execute against a DB2 instance or a DB2 database. You can use the scripting language to set the exit code or return code for the operating system script.
Notes:
A success code set is one or more comparative operators and numeric values. The comparative operators can be =, >, or <. Numeric values can be any positive or negative integer, or zero (0). All members of the success code set are compared to the SQLCODE that is returned by a DB2 command or an SQL statement, or compared to the exit code or return code that is returned by an operating system command. If the SQLCODE, exit code, or return code is within the defined set, execution of the script is considered to be successful.
The following rules apply for success code sets:
For example, if you specify (>, 5) and (<, 0), the error codes for that set are 0, 1, 2, 3, 4, 5. You cannot specify (>, 5) and (<, 6), as this will provide all numbers.
For example, if you specify (<, 0) and (>, 5), the error codes for that set are 0, 1, 2, 3, 4, 5. You cannot specify (<, 5) and (>,4), as this will provide all numbers.
The following example shows how to set up a success code set for a script that contains multiple SQL statements. Assume that each of these statements drops a table. Each DROP TABLE statement in the script will return an SQLCODE. DROP TABLE statements can return non-zero SQLCODEs that do not represent an error state. You must determine the set of SQLCODEs that do not indicate an error, and include them in the success code set for the script. For example, the following return codes indicate the successful execution of the script (that is, if any of the following conditions are met, execution of the script continues):
SQLCODE = 0, SQLCODE > 0, SQLCODE = -204
In this success code set, the SQLCODE = 0 indicates that the DROP TABLE statement completed successfully. The SQLCODE > 0 indicates that processing can continue even if a message is issued. The SQLCODE = -204 indicates that if the table does not exist when the DROP TABLE statement is issued, processing can continue.
You can create the execution target, authentication credentials, and success code set for the batch step by using the Satellite Administration Center. You can create these components of the batch step when you create the batch step, or you can create them in advance, including them when you create the batch step. For more information, refer to online help for the Satellite Administration Center.
When you administer satellites at the group level, certain types of scripts that are used in group batches need to be parameterized so that they can be executed by the satellites. You can parameterize a script to identify a value that is independent of the satellite. This is known as a table parameter. You can also parameterize a script to identify a value that is unique to a satellite (such as a user ID). This is known as a contextual parameter.
| Note: | For more information about the tables described in this section, and about
parameterizing scripts, refer to the following Web site:
www.software.ibm.com/data/db2/library/satellite |
You can add a contextual parameter to a WHERE clause to customize it for the satellites. You can find information that differs from satellite to satellite in the SATELLITES table in the satellite control database. You can also obtain this information from the satellite details view in the Satellite Administration Center. Other tables in the satellite control database that contain information to uniquely identify satellites are SAT_APPVER_PARMS and SAT_HOR_DATASLICES.
When the satellite synchronizes, requesting the group batches from the DB2 control server, the DB2 control server checks whether any script is parameterized before allowing the satellite to download it. If any script is parameterized, the DB2 control server will substitute the appropriate table or contextual parameter for the parameterized markers before the satellite downloads the script.
You specify whether a script is parameterized by using the Change Batch Steps notebook and the Create and Edit Script windows, all of which are available from the Satellite Administration Center. There are two types of parameter markers that you can use:
Table Parameters The table parameter is the general mechanism for specifying scalar values. You can use a table parameter to specify a single column value for a single row of a table in the satellite control database.
The syntax translates to SELECT colname FROM tablename WHERE predicates. The parameters are as follows:
| Note: | colname cannot resolve to a column with a data type of CLOB, BLOB, GRAPHIC(1), GRAPHIC(n), VARGRAPHIC(n), or LONG VARGRAPHIC. |
Contextual Parameters Contextual parameters refer to the values that apply specifically to the satellite that will execute a script. These values are all of the attributes of the satellite recorded in the SATELLITES table for that satellite. Other tables in the satellite control database that contain information to uniquely identify satellites are SAT_APPVER_PARMS and SAT_HOR_DATASLICES. The contextual parameter is more restrictive than a table parameter. The predicates parameter is implicitly defined to select the specific row that applies to the satellite.
Where:
| Note: | colname cannot resolve to a column with a data type of CLOB, BLOB, GRAPHIC(1), GRAPHIC(n), VARGRAPHIC(n), or LONG VARGRAPHIC. |
Examples The examples that follow show how to use parameters:
{{SATELLITES:GROUP}}
{{SATELLITES:LAST_NAME}}
{{satadmin.sat_hor_dataslices:predicates:satellite='{{SATELLITES:ID}}'
AND version='{{SATELLITES:APP_VERSION}}'
AND set_name='GROUPA'
AND group='{{SATELLITES:GROUP}}'
AND source_schema='finance'
AND whos_on_first='F'
AND source_table='expenses'
AND target_schema='finance'
AND source_view_qual=0
AND target_table='expenses'}}
When a satellite synchronizes, it obtains the scripts that it is to execute
from the DB2 control server, then stores the scripts in a location that is
specific to whether the script is for a setup, an update, or a cleanup
batch. The execution results are also stored. When the
synchronization session ends normally, the contents of these directories are
deleted. If the synchronization session is interrupted (either the user
stops the session or an abend occurs), the contents of these directories are
not deleted.
| Directory | Description | ||
|---|---|---|---|
| instance_path\satellite | The base directory for stored scripts
| ||
| instance_path\satellite\setup
instance_path\satellite\setup\results | The directory where the scripts for a setup batch are stored. Results are stored in the \results directory. | ||
| instance_path\satellite\update
instance_path\satellite\update\results | The directory where the scripts for an update batch are stored. Results are stored in the \results directory. | ||
| instance_path\satellite\cleanup
instance_path\satellite\cleanup\results | The directory where the scripts for a cleanup batch are stored. Results are stored in the \results directory. |
[ Top of Page ]