Replay Database Operation (QDBRPLAY) API

The Replay Database Operation (QDBRPLAY) API replays a database operation from a single journal entry.

Only database journal entries are supported. Since these journal entries can be quite large, use the Retrieve Journal Entries (QjoRetrieveJournalEntries) API or the Receive Journal Entry (RCVJRNE) command to retrieve the journal entry. If a journal entry is passed to QDBRPLAY that is not supported, the operation will fail. The following journal entries are supported:

You can use the QDBRPLAY API with database objects only. DDM files are not supported. File overrides do not affect the specified object names. The API does not run under commitment control even if the original journal entry was performed as part of a commitable transaction. If the specified file does not have the same File Level Identifier or Member Level Identifier as the file for which the journal entry was originally written, a warning will sent to the job log and the operation will continue.

Authorities and Locks

Object Library Authority

*EXECUTE

Note: Additionally, the same authority is necessary as the original operation. For example, if the journal entry is Create File, *ADD is required.

Object Authorities

The same authority is necessary as was required for the original operation. For example, if the journal entry is Delete File, *OBJEXIST is required.

Object Lock

*EXCL or *EXCLRD for *FILE objects.

Note: The same locks are necessary as were required during the original operation. For example, if the journal entry is Delete File, *EXCL is required. If the journal entry is Remove Member, *EXCLRD is required. Because an exclusive lock is required, concurrent applications may not access the file object identified by this API till the API has ended and any concurrent applications that hold a conflicting lock cause the API to fail.

Rename Exit Program Library Authority

*EXECUTE

Rename Exit Program Authority

*EXECUTE

Required Parameter Group

Input template

INPUT;CHAR(*)

A structure that contains the input options used to replay the operation from the journal entry. For the format of this parameter, see DBRR0100 Format.

Length of input template

INPUT; BINARY(4)

A variable that contains the length of the input template. The length must be greater than zero and large enough to contain all the template fields up to and including Disable Triggers. The length must not be larger than 32767.

Input template format name

INPUT; CHAR(8)

The format of the input template being used. The possible value is:

DBRR0100

Basic template

For more information, see DBRR0100 Format.

Journal entry specific data

INPUT;CHAR(*)

The entry specific data from a database journal entry. If the original journal entry contained any additional journal entry specific data that was addressed by a pointer, that data must be moved so that the entry specific data includes all the entry specific data immediately preceding the pointer concatenated with the entry specific data that the pointer addresses. For example, if a teraspace pointer is returned on the QjoRetrieveJournalEntries API immediately after Entry Specific Data A and points to additional Entry Specific Data B:

Entry Specific Data A

Teraspace pointer to additional data B

This must be passed to the API as:

Entry Specific Data A

Additional Entry Specific Data B

The teraspace pointer is in the last 16 bytes of the Entry Specific Data of the retrieved journal entry. The length of the data that the teraspace pointer addresses is equal to the sum of the lengths of the external command length, apply information length, and the remove information length. See member QDBJRNL in QSYSINC/H for more information.

See the Journal management topic collection for information about Entry Specific Data and Additional Entry Specific Data.

Note: The entry specific data for the database operations may be quite large, but is never larger than what will fit in a 16 megabyte space.

Length of journal entry specific data

INPUT;BINARY(4)

The length of the entry specific data from a database journal entry. The length must be greater than zero and must be the length of the actual entry specific data provided when the journal entry was originally written (including any additional journal entry specific data). The length must not be larger than 16 773 120.

Rename exit program scratchpad

INPUT; CHAR(*)

An area which is passed to the rename exit program. The area can contain any information that the caller of the API wishes to pass on to the rename exit program. A rename exit program scratchpad must be passed even if the rename exit program is not specified.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

DBRR0100 Format

The following table shows the format of the input template parameter for the DBRR0100 format. For detailed descriptions of the fields in the table, see Field Descriptions.

Offset		Type	Field
Dec	Hex
0	0	CHAR(1)	Journal code
1	1	CHAR(2)	Entry type
3	3	CHAR(10)	Rename exit program name
13	D	CHAR(10)	Rename exit program library name
23	17	CHAR(1)	Disable triggers
24	18	CHAR(1)	Rename exit program only
25	19	CHAR(*)	Reserved

Field Descriptions

Disable triggers. The disable trigger indicator controls whether new triggers that are added as a result of replaying a TC journal entry should be automatically disabled. The disable trigger indicator does not apply to Instead Of triggers.

0

Do not disable new triggers.

1

Disable new triggers.

Entry type. The journal entry type from the journal entry of the operation to replay. See the Journal management topic for more information about Entry type.

Note that a journal entry with an entry type of MN is written to the journal for both a rename member operation and for the internal operations performed as part of a rename file. If a journal entry type of MN that was written to the journal as part of a rename file operation is passed to this API, it will be ignored and no error will be returned.

Journal code. The journal code from the journal entry of the operation to replay. See the Journal management topic for more information on journal codes.

D

Database file operation.

F

Database file member operation.

Rename exit program name. The name of the rename exit program.

*NONE

A rename exit program is not provided. The names of any objects referenced during the replay of the operation will be the same as the object names that were referenced when the journal entry was originally written to the journal.

program-name

The name of the program to call which may provide a different name for any object referenced in the journal entry. When a rename exit program is specified, each name referenced during the replay of the operation will be passed to the rename exit program. The names passed to the rename exit program may be short names or long SQL names. The same name may be passed to the exit program more than once if it is referenced in the internal journal entry specific data more than once. If the names are changed by the rename exit program, the names are case sensitive and must conform to any IBM i ^® and SQL rules for object names. For example, if the new name of the object should be "a", it must be returned from the rename exit program with the quote delimiters and a lower case a. If the new name of the object should be A, it must be returned from the rename exit program in upper case without redundant quote delimiters. The following restrictions apply to referenced objects:

• The library name of an SQL type or an SQL function can be changed. The SQL type name or SQL function name cannot be changed.
• Any references to objects in the body of a program object or trigger are not renamed.
• Any references to objects in the body of an SQL view other than the based on files themselves are not renamed.
• The name of a data dictionary must be the same name as its containing library.
• The library name of a constraint must be the same as the library name of its file.

Two parameters are passed to the rename exit program. The first parameter is the Rename Exit Program Parameter Template. The second parameter is the Rename Exit Program Scratchpad. For more information, see Rename Exit Program Parameter. The exit program may inspect the name passed and leave the name as is, or it may change the name in the Rename Exit Program Parameter to an alternate name.

For example, the journal entry contains the create of an SQL table that contains a primary key constraint. The exit program will be called twice. The first call will pass the table name and library. The second call will pass the constraint name and library. If the name is a reference to another object and is changed to reference an object that does not exist, the replay of the operation will fail.

If the rename exit program returns an exception, the replay operation will fail.

Rename exit program library name. The library that contains the rename exit program, if any. The rename exit program library name must be blank if the value of the rename exit program name is *NONE.

library-name

The library name of the rename exit program.

Rename exit program only. The rename exit program only indicator controls whether the journal entry is replayed or whether the rename exit is called without replaying the journal entry. If value of the rename exit only indicator is 1, the rename exit program name must not be *NONE.

0 or '00'X

The journal entry will be replayed.

1

Only the rename exit program will be called. This option can be used to determine which objects are referenced in the journal entry without actually replaying the entry.

Reserved. A reserved field. It must contain hexadecimal zeroes.

Rename Exit Program Parameter

Offset		Type	Field
DEC	Hex
0	0	BINARY(4)	Length of rename exit program parameter
4	4	BINARY(4)	Length of object name
8	8	BINARY(4)	Length of object library
12	C	BINARY(4)	Object type
16	10	CHAR(258)	Object name
274	112	CHAR(258)	Object library name
538	21A	BINARY(4)	Object use
542	21E	CHAR(*)	Reserved

Field Descriptions

Length of rename exit program parameter. The length of the structure passed to the rename exit program. The rename exit program must not modify this value.

Length of object library name. The length of the library name of the referenced object. If the rename exit program modifies this length, it must be greater than zero and not greater than 10. It must reflect the number of characters in the new object library name.

Length of object name. The length of the name of the referenced object. If the rename exit program modifies this length, it must be greater than zero and must reflect the number of bytes in the new object name.

If the value that was passed to the rename exit program is less than or equal to 10 and the rename exit program modifies this length, the new length must also be less than or equal to 10 (a short system name cannot be renamed to a long SQL name). If the value that was passed to the rename exit program is greater than 10 the rename exit program must not modify this length (a long SQL name cannot be renamed to a short name or a long SQL name of a different length).

Object library name. The library name of the referenced object. If the rename exit program modifies the library name, it must be a valid library name.

library-name

The library name of the referenced object.

Object name. The name of the referenced object. If the rename exit program modifies the object name, it must be a valid short object name or a valid long SQL object name.

If the name passed to the exit program is not a long SQL object name, the rename exit program must not rename the object to a long SQL object name. If the name passed to the exit program is a long SQL object name, the rename exit program may rename the long SQL name to another long SQL name, but the length of the new long SQL name must be the same as the long SQL name passed to the rename exit program.

object-name

The name of the referenced object. The name may be either a short (10 character) object name or a long (258 character) SQL object name.

Object type. The type of the referenced object. The following values may be passed to the exit program for the object type:

The rename exit program must not modify this value.

While the rename exit program will be called for referenced journals, data dictionaries, and SQL types, these objects themselves cannot cannot be renamed. Furthermore, a library that contains one of these object types cannot be renamed.

Object use. The the specific use of the referenced object in the journal entry. The object use will be returned only for object types 3 and 4.

The following values are passed to the exit program for object type 3:

The following values are passed to the exit program for object type 4:

Reserved. A reserved field. The rename exit program must not modify this value.

Usage Notes

If a file is created as a result of replaying a Create File (CT) entry:

• If journaling was implicitly started when an SQL table was originally created, the replay operation will also implicitly start journaling to the same journal.
• The File level identifier for the created file will be the same as the File level identifier of the file when it was originally created.
• Any public authority that was specified by the AUT keyword when a file is created via a CL command will be granted when the file is created.

If a member is added as a result of replaying an Add Member operation (MC), the Member level identifier for the added member will be the same as the Member level identifier of the member when it was originally added.

Error Messages

[ Back to top | Database and File APIs | Journal and Commit APIs | APIs by category ]