This document covers the following topics:
The MC command is used to reduce the interprocess communications between an Adabas database and its application programs. It does not provide any additional functionality at the Adabas call interface. The MC command is a generalization of the multifetch behaviour for read commands: this generalization applies to any arbitrary sequence of Adabas commands except for BT, CL, OP and MC.
Each Adabas command of such a sequence is represented by its control block and its command buffers, which are delivered in the corresponding buffers of the MC command. The control blocks are delivered at the beginning of the record buffer. The number of different Adabas commands must be specified in 'cq_isn_quantity'.
An Adabas command sequence of an MC command can be terminated by an ET command. Only one ET command is allowed per MC command and this one must always be the last command of the sequence. If it is not the last command, the ET command will be rejected with response 22.
If a response code greater than 0 occurs during subcommand processing, the execution of further subcommands will be stopped immediately. However, an open transaction will not be backed out. The MC command returns response 16 and provides a pointer to the control block of the failed subcommand in 'cb_addition_2'.
| Field | Format | |
|---|---|---|
| Call Type | B | F/U |
| Reserved (internal use) | -/- | |
| Command Code | A | F/U |
| File Number | B | F/U (1) |
| Response Code | B | F/A (1) |
| ISN Quantity | B | F/U |
| Format Buffer Length (ACB only) | B | F/U |
| Record Buffer Length (ACB only) | B | F/U |
| Search Buffer Length (ACB only) | B | F/U |
| Value Buffer Length (ACB only) | B | F/U |
| ISN Buffer Length (ACB only) | B | F/U |
| Command Option 2 | A | F/U |
| Additions 2 | A,B | -/A |
| Command Time | B | -/A |
| User Area | F/U |
| Buffer | |
|---|---|
| Format Buffer | F/U |
| Record Buffer | F/A |
| Search Buffer | F/U |
| Value Buffer | F/U |
| ISN Buffer | F/A |
A Filled in by Adabas F To be filled in by User U Unchanged after Adabas call - Not used (1) The meaning of this field depends on the value specified for "Call Type". See Calling Adabas, The Control Block for details.
- Command Code
MC
- Response Code
Adabas returns the response code of the MC command in this field. If a subcommand terminates with a non-zero response code, Adabas returns the response code 16 in this field and stops further processing of subcommands.
- ISN Quantity
Number of subcommands delivered by the MC command. Value 0 means nothing to do.
- Format Buffer Length (ACB only)
If there is no subcommand referring to a format buffer, this length can be set to 0.
- Record Buffer Length (ACB only)
The length of the record buffer must be specified in this field. If ISN Quantity is not 0, this length must be set. The length specified must be large enough to accommodate all required record buffer entries and control blocks.
- Search Buffer Length (ACB only)
If there is no subcommand referring to a search buffer, this length can be set to 0.
- Value Buffer Length (ACB only)
If there is no subcommand referring to a value buffer, this length can be set to 0.
- ISN Buffer Length (ACB only)
If there is no subcommand referring to an ISN buffer, this length can be set to 0.
- Command Option 2
An 'S' (SHORT) in this field indicates that only the control block of the MC command is returned when no error occurs during subcommand processing.
- Additions 2
If response code 16 is returned, the following information will be returned in this field:
The first two bytes will contain the sequence number of the subcall which has received a non-zero response code;
The third and fourth bytes will contain the byte offset of the control block in the record buffer that caused the response code.
The following restrictions apply to ACBX calls: Only one of each buffer must be provided. It is not allowed to have more than one record buffer, format buffer, search buffer, value buffer or isn buffer.
The format buffer contains a buffer header (see Processing Considerations, Command Buffers) and the format buffer(s) of the subcommands. It may be omitted if no subcommand references the format buffer.
The record buffer contains a buffer header followed immediately by the control blocks of all the subcommands followed by the record buffers of the subcommands.
For ACBX commands, there are no ABDs part of the record buffer.
The search buffer contains a buffer header (see Processing Considerations, Command Buffers) and the search buffer(s) of the subcommands. It may be omitted if no subcommand references the search buffer.
The value buffer contains a buffer header (see Processing Considerations, Command Buffers) and the value buffer(s) of the subcommands. It may be omitted if no subcommand references the value buffer.
The ISN buffer contains a buffer header (see Processing Considerations, Command Buffers) and the ISN buffer(s) of the subcommands. It may be omitted if no subcommand references the ISN buffer.
The command buffers of the several subcommands will be delivered within the corresponding command buffers of the MC command. Therefore, within a buffer, several entries can be present. Each buffer must be started (offset 0) by a two-element structure. This structure contains two two-byte offsets and is called the buffer header. The buffer header indicates what is within the buffer. The buffer can contain several command buffers or only one global buffer which is used by all the subcommands. All specified offsets are relative to the beginning of the corresponding command buffer.
The C definition for the buffer header is:
struct CmdBufHd
{
unsigned short GloBuf; /* Offset to global buffer used by all subcommands */
unsigned short StartOff; /* Offset to an array of buffer start
offsets */
}
If both offsets of a buffer header are set, the corresponding MC command is rejected with response 146.
If the format buffer of an MC command contains a common format buffer for all subcommands, the 'GloBuf' offset of the buffer header must point to the common format buffer and the 'StartOff' offset must be 0.
However, the buffer may contain several different format buffers. In this case, the buffer header has an offset to a second structure, which contains the start offsets to the different format buffers. The start offsets are 2–byte fields with the subcommand sequence number as index. A zero start offset indicates that the corresponding subcommand does not refer to that command buffer.
The array of the 2-byte start offsets is position-independent, but the whole array must be delivered contiguously. The only exception is the record buffer. The control blocks of the different subcommands must always be delivered directly behind the 'Buffer Header' of the record buffer (offset=4).
If a subcommand does not use a command buffer, the corresponding offset will not be checked. A global input buffer will be ignored too if the buffer is not referred to by the command.
The control block and the ISN buffer of the subcommand must always start at an offset divisible by 4 within the corresponding MC command buffer. Because the subcommand control blocks must start directly behind the 'buffer header', the first control block always starts at offset 4 and therefore all following control blocks start automatically with a correct offset, because the control–block length is always divisible by 4. Within the ISN buffer, the user must ensure that all offsets are divisible by 4. If not, the MC command is terminated by response 146 and no subcommands are processed.
If no subcommand of the sequences refers to a command buffer, the corresponding buffer of the MC command is not necessary and the buffer size can be set to 0.
It is also possible to specify the same start offset to a command buffer from different subcommands, but it will not be permitted to use this feature to transfer data from one subcommand to a subsequent one. There is no check for record–buffer or ISN–buffer consistency. The caller is responsible for the correct specification of the subcommand output buffers to avoid overwriting.
If an error occurs, the current subcommand will be backed out, if necessary, and the execution of further subcommands will be stopped immediately. This will be done for all response codes greater than 0.
The errors will be signalled in the following way:
Errors which occur within the MC environment are returned in the control block of the MC command. 'cb_add2' does not point to a control block of a subcommand. This kind of error occurs during start or end processing of the MC command (before the first subcommand or after the last subcommand is processed).
Errors which occur during subcommand processing are returned in their control blocks. The MC command itself will return response 16, to signal that a subcommand has failed. Additions 2 points to the control block of the failed subcommand.
Response table of an MC command:
| RSP | ADD_2 (first two bytes) |
ADD_2 (last two bytes) |
Description |
|---|---|---|---|
| 16 | Number of subcommand | Offset to subcommand's control block | Error during subcommand processing. Error code and additional information are delivered in the control block of the failed subcommand. |
| 146 | Number of command buffer | Command buffer name | Incorrect MC command buffer detected (illegal buffer header, start offsets out of range, ISN buffer offset not divisible by 4,...) |
| Response of MC command | additional information if present | MC command was terminated during command start or command end processing. | |
Explanation: This response is caused by one of the following:
illegal buffer header detected (both offsets are set)
an ISN-buffer offset is not divisible by 4
'start offset array' out of MC buffer range
record buffer of MC command not big enough to contain all subcommand control blocks
invalid buffer length detected (subcommand)
The 'cb_add2' field in the control block contains additional information for response 146:
| first two bytes | last two bytes | |
|---|---|---|
| Format Buffer | 1 | FB |
| Record Buffer | 2 | RB |
| Search Buffer | 3 | SB |
| Value Buffer | 4 | VB |
| ISN Buffer | 5 | IB |
Note:
If an Adabas command with Prefetch/Multifetch option terminates with a response
during a subsequent ISN processing, this response is not returned within the
corresponding control block and therefore the MC command does not terminate with
response 16. Such a subcommand is handled like a subcommand which is successfully
terminated.
If an MC command is terminated with response 146, no subcommand has been processed.
Response table of a subcommand:
| RSP | ADD_2 (first two bytes) |
ADD_2 (last two bytes) |
Description |
|---|---|---|---|
| 146 | Number of command buffer | Command buffer name | Invalid buffer length detected, e.g. the end of subcommand buffer (offset + buffer length) is out of the corresponding MC command buffer range. |
| 22 | - | 22 23 |
Invalid command or command which is not allowed within an MC
command sequence. ET command which is not the last command of an MC subcommand sequence. |
| Response of command | additional information if present | Subcommand processing was terminated by response code 'rsp'. | |