| **Navigation:**  [[introduction.htm|Language Reference]] > 13 - Built-in Functions >====== ADD (add an entry) ====== | [[acos  return arccosine .htm|{{btn_prev_n.gif|Previous page}}]][[introduction.htm|{{btn_home_n.gif|Return to chapter overview}}]][[address  return memory address .htm|{{btn_next_n.gif|Next page}}]] |
|  ||

|  | |// file// | |
|  | |// file// ,//length//| |
| **ADD(** | |// queue//| **)** |
|  | |// queue//, [**+**]//key//,...,[**-**]//key//]| |
|  | |// queue//, //name//| |
|  | |// queue//, //function//| |
|  | |// queue//, //pointer//| |

{{blk2blue.jpg|blk2blue.jpg}}

| **ADD** | Writes a new record to a FILE or QUEUE. |
| //file// | The label of a FILE declaration. |
| //length// | An integer constant, variable, or expression which contains the number of bytes in the RECORD buffer to write to the //file//. If omitted or out of range, //length// defaults to the length of the RECORD structure. |
| //queue// | The label of a QUEUE structure, or the label of a passed QUEUE parameter. |
| + - | The leading plus or minus sign specifies the //key// is sorted in ascending or descending sequence. If omitted, ascending sequence is the default. |
| //key// | The label of a field declared within the QUEUE structure. If the QUEUE has a PRE attribute, the //key// must include the prefix. |
| //name// | A string constant, variable, or expression containing the NAME attribute of QUEUE fields, separated by commas, and optional leading + or - signs for each attribute. This parameter is case sensitive. |
| //function// | The label of the function containing two parameters of a *GROUP or named GROUP passed by address, and having a SIGNED return value. Both parameters must use the same parameter type, and cannot be omitted. The RAW, C and PASCAL attributes are not permitted in the prototype declaration. See [[additional queue considerations.htm#queuekeyparameter|Additional Queue Considerations]]. |
| //pointer// | A numeric constant, variable, or numeric expression. The //pointer// must be in the range from 1 to the number of entries in the memory queue. |

The **ADD** statement writes a new record to a FILE or QUEUE.

**FILE Usage**

{{black.jpg|black.jpg}}

All KEYs associated with the //file// are also updated during each ADD. If there is no room for the record on disk, the "Access Denied" error is posted. If an error is posted, no record is added to the file.

You can use the DUPLICATE procedure to check whether the ADD will return the "Creates Duplicate Key" error. The DUPLICATE procedure assumes that the contents of the RECORD structure data buffer are duplicated at the current record pointer location. Therefore, when using DUPLICATE prior to ADDing a record, the record pointer should be cleared with: GET(//file//,0).

| ADD(//file//) | Adds a new record to the //file// by writing the entire contents of the data file's record buffer to disk. |
| ADD(//file,length//) | Adds a new record to the //file //by writing //length// number of bytes from the data file's record buffer to disk. The //length// must be greater than zero and not greater than the length of the RECORD. This form of ADD is not supported by all file drivers--check your file driver documentation. |

**QUEUE Usage**

{{black.jpg|black.jpg}}

ADD writes a new entry from the QUEUE structure data buffer to the QUEUE. If there is not enough memory to ADD a new entry, the "Insufficient Memory" error is posted.

| ADD(//queue//) | Appends a new entry to the end of the QUEUE. |
| ADD(//queue,pointer//) | Places a new entry at the relative position specified by the //pointer// parameter. If there is an entry already at the relative //pointer// position, it is "pushed down" to make room for the new entry. All following pointers are readjusted to account for the new entry. For example, an entry added at position 10 pushes entry 10 to position 11, entry 11 to position 12, etc. If //pointer// is zero or greater than the number of entries in the QUEUE, the entry is added at the end. |
| ADD(//queue,key//) | Inserts a new entry in a sorted memory queue. Multiple //key// parameters may be used (up to 16), separated by commas, with optional leading plus or minus signs to indicate ascending or descending sequence. The entry is inserted immediately after all other entries with matching //key// values. Using only this form of ADD will build the QUEUE in sorted order. |
| ADD(//queue,name//) | Inserts a new queue entry in a sorted memory queue. The //name// string must contain the NAME attributes of the fields, separated by commas, with optional leading plus or minus signs to indicate ascending or descending sequence. The entry is inserted immediately after all other entries with matching field values. If there are no entries, ADD(//queue,name//) may be used to build the QUEUE in sorted order. |
| ADD(//queue,function)// | Using ADD by FUNCTION will write from a positional value returned by the function. If the function returns zero (0) the queue record of the first parameter is treated as equal to the second. In this case, no record is added, since the values are equal. If the function returns a negative value, the ADD of the record passed as a first parameter is treated as having less value than record passed as second parameter and is written accordingly. If the function returns a positive value, the ADD of the record passed as a first parameter is treated as having a greater value than record passed as second parameter and is written accordingly. |

If the QUEUE contains any reference variables or fields with the ANY data type, you must first CLEAR the QUEUE entry before assigning new values to the component fields of the QUEUE. This avoids possible memory leaks, since these data types automatically allocate memory.

**Errors Posted:**

| 05 | Access Denied |
| 08 | Insufficient Memory |
| 37 | File Not Open |
| 40 | Creates Duplicate Key |
| 75 | Invalid Field Type Descriptor |

**Example:**

**NameQue  QUEUE**

**Name      STRING(20),NAME('FirstField')**

**Zip       DECIMAL(5,0),NAME('SecondField')**

**AnyField  ANY**

**         END**

** CODE**

** ****ADD****(Customer)                           !Add a new customer file record**

** IF ERRORCODE() THEN STOP(ERROR()).      !and check for errors**

** NameQue.Name = 'Jones'                  !Assign data**

** NameQue.Zip = 12345**

** NameQue.AnyField &= NEW(STRING(10))     !Create a new STRING(10) field in the QUEUE**

** ****ADD****(NameQue)                            !Add an entry to the end of the QUEUE**

** CLEAR(NameQue)                          !Clear ANY for next entry**

** NameQue.Name = 'Taylor'                 !Assign data**

** NameQue.Zip = 12345**

** NameQue.AnyField &= NEW(STRING(20))     !Create a new STRING(20) field in the QUEUE**

** ****ADD****(NameQue,+NameQue.Name,-NameQue.Zip) !Ascending name, descending zip order**

** CLEAR(NameQue)                          !Clear ANY for next entry**

** NameQue.Name = 'Adams'                  !Assign data**

** NameQue.Zip = 12345**

** NameQue.AnyField &= NEW(STRING(30))     !Create a new STRING(30) field in the QUEUE**

** ****ADD****(NameQue,1)                          !Add an entry at position 1**

** CLEAR(NameQue)                          !Clear ANY for next entry**

** Que:Name = 'Smith'                      !Assign data**

** Que:Zip = 12345**

** NameQue.AnyField &= NEW(STRING(40))     !Create a new STRING(40) field in the QUEUE**

** ****ADD****(NameQue,+FirstField,-SecondField)   !Ascending name, descending zip order**

** CLEAR(NameQue)                          !Clear ANY for next entry**

**See Also:**

[[sort  sort queue entries .htm|SORT]]

[[clear  clear a variable .htm|CLEAR]]

[[reference variables.htm|Reference Variables]]

[[put  re write record .htm|PUT]]

[[get  read a record or entry .htm|GET]]

[[duplicate  check for duplicate key entries .htm|DUPLICATE]]

[[append  add a new file record .htm|APPEND]]