ADD (add an entry)

Top  Previous  Next

 

 

| file |

 

| file ,length|

ADD(

| queue| )

 

| queue, [+]key,...,[-]key]|

 

| queue, name|

 

| queue, function|

 

| queue, pointer|

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.

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

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

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

CLEAR

Reference Variables

PUT

GET

DUPLICATE

APPEND