This document covers the following topics:
The N1 command is used to add a new record to a file.
The user specifies the file to which the record is to be added and the fields for which values are being provided. Any fields not specified will contain a null value in the record added.
Adabas assigns the record an ISN, adds the record to Data Storage and performs any Associator updating which may be required.
The N2 command is used if the ISN to be assigned to the record is provided by the user, regardless of whether REUSE=ISN is specified in ADAFDU.
If the user is an ET logic user, the record added is placed in exclusive hold status.
| Field | Format | |
|---|---|---|
| Call Type | B | F/U |
| Reserved (internal use) | -/- | |
| Command Code | A | F/U |
| Command ID | B | F/U |
| File Number | B | F/U (1) |
| Response Code | B | F/A (1) |
| ISN | B | * |
| Format Buffer Length (ACB only) | B | F/U |
| Record Buffer Length (ACB only) | B | F/U |
| Additions 2 | A,B | -/A |
| Additions 3 | A | F/A |
| Additions 5 | A | F/U |
| Command Time | B | -/A |
| User Area | F/U |
| Buffer | |
|---|---|
| Format Buffer | F/U |
| Record Buffer | F/U |
| Search Buffer | –/– |
| Value Buffer | –/– |
| ISN Buffer | –/– |
| A | alphanumeric |
| B | binary |
| A | Filled in by Adabas |
| F | To be filled in by User |
| U | Unchanged after Adabas call |
| - | Not used |
| * | –/A for N1; F/U for N2 |
(1) The meaning of this field depends on the value specified for "Call Type". See Calling Adabas, The Control Block for details.
N1/N2
If a series of records is being added using a series of N1/N2 calls and the same fields are specified in the format buffer for each call, this field should be set to a non-blank, non-zero value. This results in a reduction in the time required to process each N1/N2 call.
If only a single record is being added, or if the format buffer is modified between N1/N2 calls, this field should be set to blanks or binary zeros.
The high-order byte of this field must not be set to hexadecimal `FF', except when automatic command ID generation is used (see Programming Considerations, Command IDs for additional information).
The number of the file to which the record is to be added.
Adabas returns the response code for the command in this field. Response code 0 indicates that the command was executed successfully.
If the N1 command is being used, Adabas returns the ISN assigned to the record in this field.
If the N2 command is being used, the ISN to be assigned to the record must be provided in this field. The ISN provided must not already be assigned to a record in the file and must be within the limit (MAXISN) in effect for the file. MAXISN is set by the DBA when the file is loaded.
The format buffer length (in bytes). The format buffer area defined in the user program must be as large as (or larger than) the length specified.
The record buffer length (in bytes). The record buffer area defined in the user program must be as large as (or larger than) the length specified.
If response code 0 is returned, Adabas returns the compressed record length of the record added in this field. The length is provided in the first two bytes in binary format.
For some response codes, Adabas returns detailed information in this field. See Adabas Messages And Codes for further information.
This field is used to provide a security password.
If the file to be used is not security protected, this field should be set to blanks. If the file is security protected, the user must provide a valid password.
Adabas sets this field to blanks during command processing to protect the integrity of any password provided.
This field may be used to provide a separate format buffer ID that is used to identify the internal format buffer used for this command, or to provide a global format buffer ID.
As long as the first byte of the Additions 5 field is not alphanumeric, the value provided in the command ID field will also be used as the format buffer ID.
If the first byte is a lower case character, the bytes 5 to 8 of the Additions 5 field will be used as the separate local format buffer ID.
If the first byte is a digit or an upper case character, the Additions 5 field (8 bytes) will be used as a separate global format buffer ID, which means that the format buffer ID can be used by several users in parallel.
See Programming Considerations, Using Command IDs for additional information and examples.
The fields for which values are being provided in the record buffer must be specified in this buffer.
The syntax and examples of format buffer construction are provided in Calling Adabas, Format and Record Buffers.
Any fields which are not specified will contain a null value in the record being added.
All non-NU descriptors which are not specified in the format buffer will have null values in the inverted list.
For non-NU descriptors which are contained in a periodic group, null values will be entered in the inverted list only for null occurrences which precede the highest occurrence number specified in the format buffer.
The value for each field specified in the format buffer must be provided in this buffer.
Each value must be provided according to the standard length and format of the field for which the value is being provided, unless a different length and/or format is specified in the format buffer.
If the field is defined as a variable length field (no standard length), a one byte binary field containing the length of the field (including the length byte) must be provided immediately before the value.
If the field for which the value is being provided is defined as a unique descriptor, the value provided must not already exist for the descriptor; otherwise, error response 98 will be returned.
The following additional considerations are applicable for the N1/N2 command:
Subdescriptors, superdescriptors, and phonetic descriptors may not be specified in the format buffer. Adabas automatically creates the correct value for any of the above if a field, from which a subdescriptor, superdescriptor, or phonetic descriptor is derived, is specified in the format buffer.
The maximum record length after compression (including record ISN) is the maximum available DATA storage block size - 4.
A descriptor value may not exceed 1144 bytes, unless the descriptor is defined with the TR option.
If a field is specified using a length override which exceeds the standard length (not permitted if the field is defined with the fixed storage option), all subsequent references to this field should specify the length which was used. If a subsequent reference uses the standard length, value truncation for alphanumeric fields (if OPTIONS=TRUNCATION is specified) or a non–zero response code for numeric fields may occur.
Field names withput index may be specified more than once only if they are multiple-value fields. Multiple-value fields and fields in periodic groups with the same index may not be specified more than once. It is also forbidden to specify a group and a field in the group at the same time.
Numeric edit masks must not be specified in the format buffer.
A multiple-value count field or periodic-group count field specified in the format buffer will be ignored by Adabas. The corresponding value in the record buffer will also be ignored. A literal in the format buffer will be ignored by Adabas. The corresponding positions in the record buffer will also be ignored.
If a multiple-value field is specified in the format buffer, Adabas sets the multiple-value field count according to the following rules:
For a multiple-value field defined with the NU option, the count field is adjusted to reflect the number of existing non–blank values. Blank values are completely suppressed.
| Field Definition Format Buffer Record Buffer Result after add |
01,MF,5,A,MU,NU MF1-3 XXXXXYYYYYZZZZZ XXXXX,YYYYY,ZZZZZ MF count = 3 |
| Format Buffer Record Buffer Result after add |
MF1-3 XXXXXbbbbbZZZZZ XXXXX,ZZZZZ MF count = 2 |
| Format Buffer Record Buffer Result after add |
MF1-3 bbbbbbbbbbbbbbb (blanks) Values suppressed MF count = 0 |
For a multiple–value field defined without the NU option, the count is adjusted to reflect the number of existing values (including null values).
| Field Definition Format Buffer Record Buffer Result after add |
01,MF,5,A,MU MF1-3 XXXXXYYYYYbbbbb XXXXX,YYYYY,b(blank) MF count = 3 |
| Format Buffer Record Buffer Result after add |
MF1 bbbbb (blanks) b (blank) MF count = 1 |
If a periodic group or a field within a periodic group is specified in the format buffer, Adabas sets the periodic group count equal to the highest occurrence number specified in the format buffer. If the highest occurrence is null–value suppressed, the count is adjusted accordingly.
| Field Definitions | 01,GB,PE 02,BA,1,B,DE,NU 02,BB,5,P,NU |
| Format Buffer Record Buffer |
GB1-2. 0x08000000500C09000000600C (or ^X08000000500C09000000600C) |
| Result after add | GB (1st occurrence) BA = 8 BB = 500 GB (2nd occurrence) BA = 9 BB = 600 GB count = 2 |
| Format Buffer Record Buffer |
GB1-2. 0x00000000000C00000000000C (or ^X00000000000C00000000000C) |
| Result after add | GB (1st occurrence) Values Suppressed GB (2nd occurrence) Values Suppressed GB count = 0 |
If a field defined with variable length (no standard length), as specified in the format buffer, the corresponding value in the record buffer must be preceded by a one byte binary number which represents the length of the value (including the length byte).
| Field Definitions | 01,AA,3,A 01,AB,0,A |
| Format Buffer Record Buffer |
AA,AB. 0x313233063132333435 (or ^X3132330631323334350) |
Fields AA and AB are to be added. The value for AA is 123. the value for AB (which is a variable length field) is 12345.
A record is to be added to file 1. The ISN of the record is to be assigned by Adabas. The field values which are to be provided are:
| FIELD | VALUE |
| AA | ABCD |
| MF (value 1) | AAA |
| MF (value 2) | BBB |
| BA (1st occurrence) | 5 |
| BA (2nd occurrence) | 6 |
Command Code N1
Command ID bbbb (only 1 record being added)
File Number 1
Format Buffer Length 15 (or larger)
Record Buffer Length 16 (or larger)
Additions 3 bbbbbbbb (file 1 not security protected)
Format Buffer AA,MF1-2,BA1-2.
Record Buffer 0x61626364202020206161616262620506
(or ^X61626364202020206161616262620506)
A record is to be added to file 2. The ISN of the record is to be provided by the user. The field values to be provided are:
| FIELD | VALUE |
| RA | 12345678 |
| RB | ABCD |
Command Code N2
Command ID bbbb (only 1 record is to be added)
File Number 2
ISN 20 (ISN 20 is to be assigned to the
record)
Format Buffer Length 6 (or larger)
Record Buffer Length 18 (or larger)
Additions 3 Password (file 2 is security protected)
Format Buffer RA,RB.
Record Buffer 0x313233343536373861626364202020202020
(or ^X313233343536373861626364202020202020)