N1/N2 Command (Add Record)

This document covers the following topics:

Function and Use

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.

graphics/n1n2.png

N1/N2 Command, Procedure Flow

Control Block

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 Areas

Buffer  
Format Buffer F/U
Record Buffer F/U
Search Buffer –/–
Value Buffer –/–
ISN Buffer –/–
Formats:
A alphanumeric
B binary
x/y before/after Adabas call - x and y can take the values:
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.

Control Block

Command Code

N1/N2

Command ID

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).

File Number

The number of the file to which the record is to be added.

Response Code

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

ISN

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.

Format Buffer Length (ACB only)

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.

Record Buffer Length (ACB only)

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.

Additions 2

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.

Additions 3

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.

Additions 5

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.

Format Buffer

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.

Record 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.

Additional Considerations

The following additional considerations are applicable for the N1/N2 command:

  1. 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.

  2. The maximum record length after compression (including record ISN) is the maximum available DATA storage block size - 4.

  3. A descriptor value may not exceed 1144 bytes, unless the descriptor is defined with the TR option.

  4. 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.

  5. 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.

  6. Numeric edit masks must not be specified in the format buffer.

  7. 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.

  8. 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

  9. 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

  10. 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.

Examples

Example 1:

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

Control Block:

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)

Buffer Areas:

Format Buffer         AA,MF1-2,BA1-2.

Record Buffer         0x61626364202020206161616262620506
                      (or ^X61626364202020206161616262620506)

Example 2:

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

Control Block:

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)

Buffer Areas:

Format Buffer         RA,RB.

Record Buffer         0x313233343536373861626364202020202020
                      (or ^X313233343536373861626364202020202020)