C3 Command: Write Checkpoint

#### Search Results

Search

# C3 Command: Write Checkpoint

The C3 command writes a SYNX-03 checkpoint in the Adabas checkpoint file.

We recommend that you set unused ACB and ACBX fields to binary zeros before the direct call is initiated.

This document covers the following topics:

- Function and Use

- ACB Interface Direct Call: C3 Command

- ACBX Interface Direct Call: C3 Command

- Buffers

## Function and Use

The C3 command may be issued only by exclusive control/update users (who are not using ET logic).

The primary function of the C3 command is to write a SYNX-03 checkpoint in the Adabas checkpoint file. This checkpoint entry:

- contains the current data protection log and block number.

- may be used to restore the database (or certain files) to the status in effect at the time the checkpoint was taken. This may be necessary before a program performing exclusive control updating can be rerun or restarted.

If Command Option 2 is specified, the C3 command also stores user data in the Adabas checkpoint file for restart purposes. The stored data may be subsequently read with an OP or RE command.

## ACB Interface Direct Call: C3 Command

This section describes ACB interface direct calls for the C3 command. It covers the following topics:

- Control Block and Buffer Overview

- Control Block Field Descriptions

- ACB Example

### Control Block and Buffer Overview

#### 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-35 | -- | -- | --
Command Option 2 | 36 | alphanumeric | F | U
| 37-72 | -- | -- | --
Command Time | 73-76 | binary | -- | A
User Area | 77-80 | -- | -- | U

#### Buffer Areas

Buffer | Before Adabas Call | After Adabas Call
--- | --- | ---
Format | * |
Record | F | U

where:

F | Supplied by user before Adabas call
A | Supplied 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 a database other than the application's default database (read in by ADARUN DBID parameter, provided in the loaded link globals table, or linked with the link routine).
-- | Not used

### Control Block Field Descriptions

We recommend that you set unused ACB fields to binary zeros before the direct call is initiated.

> Command Code (ACBCMD)

>   C3

> File Number (ACBFNR)

>   A database ID is only necessary if you are accessing a database other than the application's default database (read in by ADARUN DBID parameter, provided in the loaded link globals table, or linked with the link routine).

> Response Code (ACBRSP)

>   Adabas returns the response code for the command in this field. Response code 0 (ADARSP000) indicates that the command was executed successfully.

>   Response codes and their subcodes are defined in the Adabas Messages and Codes Manual documentation.

> Record Buffer Length (ACBRBL)

>   This field is used only if Command Option 2 is specified.

>   The number of bytes of user data to be stored must be specified in this field.

>   The maximum length that may be specified is 2000 bytes.

> Command Option 2: Store User Data (ACBCOP2)

>   Option | Description
>   --- | ---
>   E | Indicates that user data is to be stored in the Adabas checkpoint file when the session terminates. This option is only available if you provided a non-blank, unique user ID during the OP command for the user session.

### ACB Example

A user program issues a C3 command and provides user data to be stored in the Adabas checkpoint file.

#### Control Block

Command Code | C3 |
Record Buffer Length | 17 | 17 bytes of user data to be stored
Command Option 2 | E | user data is to be stored

#### Buffer

Record Buffer | EXU-USER ET-DATA

## ACBX Interface Direct Call: C3 Command

This section describes ACBX interface direct calls for the C3 command. It covers the following topics:

- Control Block and Buffer Overview

- Control Block Field Descriptions

### Control Block and Buffer Overview

#### Control Block

Field | Position | Format | Before Adabas Call | After Adabas Call
--- | --- | --- | --- | ---
| 1-2 | --- | --- | ---
Version Indicator | 3-4 | binary | F | U
| 5-6 | --- | --- | ---
Command Code | 7-8 | alphanumeric | F | U
| 9-10 | --- | --- | ---
Response Code | 11-12 | binary | --- | A
--- | 13-16 | --- | --- | ---
Database ID** | 17-20 | numeric | F | U
| 21-49 | --- | --- | ---
Command Option 2 | 50 | alphanumeric | F | U
| 51-114 | --- | --- | ---
Error Subcode | 115-116 | binary | --- | A
| 117-144 | --- | --- | ---
Command Time | 145-152 | binary | --- | A
User Area | 153-168 | not applicable | --- | U
| 169-193 | --- | --- | ---

#### ABDs and Buffers

ABD and Buffer | Before Adabas Call | After Adabas Call
--- | --- | ---
Format | * |
Record | F | U

where:

F | Supplied by user before Adabas call
A | Supplied by Adabas
U | Unchanged after Adabas call
* | Not used but should be included in Adabas call or one will be automatically generated.
** | A database ID is only necessary if you are accessing a database other than the application's default database (read in by ADARUN DBID parameter, provided in the loaded link globals table, or linked with the link routine).
-- | Not used

### Control Block Field Descriptions

We recommend that you set unused ACBX fields to binary zeros before the direct call is initiated.

> Version Indicator (ACBXVER)

>   F2

> Command Code (ACBXCMD)

>   C3

> Response Code (ACBXRSP)

>   Adabas returns the response code for the command in this field. Response code 0 (ADARSP000) indicates that the command was executed successfully. Non-zero response codes, which can also have accompanying subcodes returned in the Error Subcode (ACBXERRC) field, are described in the Adabas Messages and Codes Manual documentation.

> Database ID (ACBXDBID)

>   Use this field to specify the database ID only if you are accessing a database other than the application's default database (read in by ADARUN DBID parameter, provided in the loaded link globals table, or linked with the link routine). The Adabas call will be directed to this database.

>   This field is a four-byte binary field, but at this time only two-byte database IDs are supported. Therefore, the database ID should be specified in the low-order part (rightmost bytes) of the field, with leading binary zeros.

>   If this field is set to binary zeros, the Adabas API uses either the database ID from the ADARUN cards provided in DDCARD input data or the default database ID value provided in the LNKGBLS module linked with or loaded by the link routine.

> Command Option 2: Store User Data (ACBXCOP2)

>   Option | Description
>   --- | ---
>   E | Indicates that user data is to be stored in the Adabas checkpoint file when the session terminates. This option is only available if you provided a non-blank, unique user ID during the OP command for the user session.

> Error Subcode (ACBXERRC)

>   If the command returns a nonzero response code, this field contains a subcode defining the exact response code meaning. Response codes and their subcodes are defined in the Adabas Messages and Codes Manual documentation.

## Buffers

The following buffers apply to a C3 command:

- Format Buffer

- Record Buffer

### Format Buffer

A format buffer is not used by the C3 command, but should be included in the Adabas call. If this is an ACB interface direct call and a format buffer is not specified, a processing error will occur; ACB interface direct calls expect buffers to be specified in a set sequence. If this is an ACBX interface direct call and a format buffer is not specified, one will be automatically generated.

### Record Buffer

The record buffer contains the user data to be stored in the Adabas checkpoint file. The number of bytes actually stored is determined by the value specified in the record buffer length field.

The user data is retained only if you issued an OP command for the user session in which a non-blank, unique user ID was provided. The data is retained until you issue the next C3 or CL command in which user data is provided. If a non-blank, unique user ID was not provided, the data cannot be retrieved in a subsequent session.

### On this page

- Function and Use
- ACB Interface Direct Call: C3 Command
- ACBX Interface Direct Call: C3 Command
- Buffers