C5 Command: Write User Data to Protection Log

The C5 command writes user data on SIBA/PLOG. If you have Event Replicator for Adabas installed, however, you can also use the C5 command to send messages from the originating application to one or more Event Replicator Server destinations.

This document covers the following topics:


Function and Use

The C5 command is used to write user data to the Adabas data protection log. This data may be read and displayed using the ADASEL utility. The data that is written has no effect on Adabas recovery processing. The ADASAV and ADARES utilities ignore all data written to the data protection log as a result of a C5 command.

If you have Event Replicator for Adabas installed, you can also use the C5 command to send a message from your application to one or more Event Replicator Server destinations. This C5 command must specify a file number (to identify the file to which the C5 command applies) and its Command Option 1 control block field must be set to "R". When a C5 command with the R-option is specified, Adabas sends the data to the Event Replicator Server as a user-defined event, in addition to writing the user data to the PLOG (where it can be read and displayed using the ADASEL utility). Adabas and the Event Replicator Server do not alter or convert the user data sent with a C5 command with the R option; therefore, you must ensure that the user data is sent in a format that the target application receiving the data understands.

If you specify the C5 command with the R option, you may optionally specify a subscription name in the Addition 1 control block field, however the subscription must be previously defined to the Event Replicator Server. The Event Replicator Server destinations to which the message is passed are determined from the subscription, if one is specified, or, if no subscription is specified, from all destinations of subscriptions for the specified file. If no destination can be determined (either because the specified subscription does not exist or because no subscriptions for the specified file exist), the message is not processed and will be discarded. The only auditing of discarded messages could be in the Replication transaction logging (TLOG) file.

Command: C5

User Control Block

Field Position Format Before Adabas Call After Adabas Call
  1-2 -- -- --
COMMAND CODE 3-4 alphanumeric F U
  5-8 -- -- --
FILE NUMBER** 9-10 binary F U
RESPONSE CODE 11-12 binary -- A
  13-26 -- -- --
RECORD BUFFER LENGTH 27-28 binary F U
  29-34 -- -- --
COMMAND OPTION 1*** 35 alphanumeric, only value of "R" allowed F U
  36 -- -- --
ADDITIONS 1*** 37-44 alphanumeric F U
  45-72 -- -- --
COMMAND TIME 73-76 binary -- A
USER AREA 77-80 -- -- U

User Buffer Areas

Buffer Before Adabas Call After Adabas Call
FORMAT BUFFER *  
RECORD BUFFER F U

where:

F Filled in by user before Adabas Call
A Filled in by Adabas
U Unchanged after Adabas call
* Not used but must be included in parameter list of call statement
** A database ID is only necessary if you are accessing multiple databases and need to limit the command operation to a specific database.

However, if you are using Event Replicator for Adabas and the Command Option 1 field is set to "R", a file number must be specified to identify the file to which the C5 command applies.

*** Only used if you are using Event Replicator for Adabas. For more information, read your Event Replicator for Adabas documentation.
-- Not used

Control Block

Command Code

C5

File Number

When "R" is specified in the Command Options 1 field, this field is required to identify the file to which the C5 command applies. The file number may be one or two bytes. If the specified file is not a replicated file, appropriate response codes are returned.

Adabas sends the user data and optional subscription name to the Event Replicator Server associated with the file for further processing.

If "R" is not specified in the Command Options 1 field, this field should not be specified.

Response Code

Adabas returns the response code for the command in this field. Response code 0 indicates that the command was executed successfully. If the C5 command returns a non-zero response code, the rightmost two bytes of the Adabas control block, bytes 45-48 (additions 2 field) may contain a subcode defining the exact response code meaning. Response codes and their subcodes are defined in the Adabas messages and codes documentation.

Record Buffer Length

The number of bytes specified in this field will be written to the Adabas data protection log.

The maximum length which may be specified is 2048 bytes.

Command Options 1

When the Event Replicator for Adabas is installed, a value of "R" is allowed in this field to identify that the command is intended for the Event Replicator Server.

If the Event Replicator for Adabas is not installed, this field must be blank.

Additions 1

When "R" is specified in the Command Options 1 field, an optional subscription name can be specified in this field. The subscription must have been previously defined to the Event Replicator Server.

If "R" is not specified in the Command Options 1 field, this field should not be specified.

Record Buffer

The information to be written to the data protection log is provided in this buffer. If option "R" has been specified in the Command Options 1 field, Adabas also sends the information to the Event Replicator Server associated with the specified file.

The written information may be selected subsequently using the ADASEL utility by specifying the beginning characters (1 to 30 characters) as originally contained in the record buffer. It is, therefore, recommended that the user provide a unique identification of his data in the beginning positions of the record buffer. This will ensure that the user data can be properly identified and selected.

Examples

This section provides the following examples:

Non-Replication Example

In this example, the information "ULRR0422 UPDATES FOR JANUARY" is written to the Adabas data protection log.

Control Block

Command Code C5
Record Buffer Length 28

Buffer Areas

Record Buffer ULRR0422 UPDATES FOR JANUARY

Replication Example

In this example, the information "REPLICATION DATA RECEIVED" is sent to the Event Replicator Server destinations identified by subscription SUBSCR01 for Adabas file 12.

Control Block

Command Code C5
File Number 12
Record Buffer Length 25
Command Options 1 R
Additions 1 SUBSCR01

Buffer Areas

Record Buffer REPLICATION DATA RECEIVED