| **Navigation:**  [[introduction.htm|Language Reference]] > 13 - Built-in Functions >====== PUT (re-write record) ====== | [[pusherrors write error information .htm|{{btn_prev_n.gif|Previous page}}]][[introduction.htm|{{btn_home_n.gif|Return to chapter overview}}]][[putini set ini file entry .htm|{{btn_next_n.gif|Next page}}]] | | || | | **PUT** | **(**| //file// [,// filepointer// [,// length //] ] | **)** | | | | | //queue// , [[**+**]//key//,...,[**-**]//key//]| | | | | |// queue// ,// name//| | | | | |// queue// ,// function//| | | | | | //view//| | {{blk2blue.jpg|blk2blue.jpg}} | **PUT** | Writes a record back to a FILE, QUEUE, or VIEW. | | //file// | The label of a FILE declaration. | | //filepointer// | A numeric constant, variable, or expression for the value returned by the POINTER(//file//) procedure. | | //length// | An integer constant, variable, or expression containing the number of bytes to write to the //file//. This must be greater than zero and not greater than the RECORD length. If omitted or out of range, the RECORD length is used. | | //queue// | The label of a QUEUE structure. | | **+ -** | The leading plus or minus sign specifies the //key// is sorted in ascending or descending sequence. | | //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]]. | | //view// | The label of a VIEW declaration. | The **PUT** statement re-writes a previously accessed record in a FILE, QUEUE, or VIEW. **FILE Usage** {{black.jpg|black.jpg}} The **PUT** statement writes the current values in the RECORD structure data buffer to a previously accessed record in the //file//. If the record was held, it is automatically released. | PUT(//file//) | Writes back the last record accessed with NEXT, PREVIOUS, GET, or ADD. If the values in the key variables were changed, the KEYs are updated. | | PUT(//file,filepointer//) | Writes the record to the //filepointer// location in the //file// and the KEYs are updated. | | PUT(//file,filepointer,length//) | Writes //length// bytes to the //filepointer// location in the //file// and the KEYs are updated. | If a record was not accessed with NEXT, PREVIOUS, GET, REGET, ADD, or was deleted, the "Record Not Available" error is posted. PUT also posts the "Creates Duplicate Key" error. If any error is posted, the record is not written to the file. **QUEUE Usage** {{black.jpg|black.jpg}} **PUT** writes the contents of the data buffer back to the QUEUE (after a successful GET or ADD) to the position returned by the POINTER procedure. If no previous GET or ADD was executed, the "Entry Not Found" error is posted. | PUT(//queue//) | Writes the data buffer back to the same relative position within the QUEUE of the last successful GET or ADD. | | PUT(//queue,key//) | Writes an entry to a sorted memory queue after a successful GET or ADD, maintaining the sort order if any //key// fields have changed value. 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. | | PUT(//queue,name//) | Writes an entry to a sorted memory queue after a successful GET or ADD, maintaining the sort order if any key fields have changed value. 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. | | PUT(//queue,function//) | Using PUT 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 written, since the values are equal. If the function returns a negative value, the PUT 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 PUT 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. | **VIEW Usage** {{black.jpg|black.jpg}} The **PUT** statement writes the current values in the VIEW structure's primary file's data buffer to a previously accessed primary file record in the //view//. If the record was held, it is automatically released. PUT writes to the last record accessed with the REGET, NEXT, or PREVIOUS statements. If the values in the key variables were changed, then the KEYs are updated. PUT only writes to the primary file in the VIEW because the VIEW structure performs both relational Project and Join operations at the same time. Therefore, it is possible to create a VIEW structure that, if all its component files were updated, would violate the Referential Integrity rules set for the database. The common solution to this problem in SQL-based database products is to write only to the Primary file. Therefore, Clarion has adopted this same industry standard solution. If a record was not accessed with REGET, NEXT, or PREVIOUS statements, or was deleted, then the "Record Not Available" error is posted. PUT also posts the "Creates Duplicate Key" error. If any error is posted, then the record is not written to disk. **Errors Posted:** | 05 | Access Denied | | 08 | Insufficient Memory | | 30 | Entry Not Found | | 33 | Record Not Available | | 40 | Creates Duplicate Key | | 75 | Invalid Field Type Descriptor | | 89 | Record Changed By Another Station | **Example:** ViewOrder VIEW(Header) JOIN(Dtl:OrderKey,Hea:OrderNumber) !Join Detail file PROJECT(Det:Item,Det:Quantity) END END NameQue QUEUE,PRE(Que) Name STRING(20),NAME('FirstField') Zip DECIMAL(5,0),NAME('SecondField') END CODE OPEN(Header,22h) OPEN(Detail,22h) SET(Cus:AcctKey) OPEN(ViewOrder) LOOP !Read all records in reverse order PREVIOUS(ViewOrder) ! read a record sequentially IF ERRORCODE() THEN BREAK. ! break at beginning of file DO LastInFirstOut !Call last in first out routine PUT(ViewOrder) !Write transaction record back to the file IF ERRORCODE() THEN STOP(ERROR()) END END !End loop DO BuildQue !Call routine to build the queue Que:Name = 'Jones' !Initialize key field GET(NameQue,Que:Name) !Get the matching record IF ERRORCODE() THEN STOP(ERROR()) END Que:Zip = 12345 !Change the zip PUT(NameQue) !Write the changes to the queue IF ERRORCODE() THEN STOP(ERROR()) END Que:Name = 'Jones' !Initialize key field GET(NameQue,Que:Name) !Get the matching record IF ERRORCODE() THEN STOP(ERROR()) END Que:Name = 'Smith' !Change key field PUT(NameQue,Que:Name) !Write changes to the queue IF ERRORCODE() THEN STOP(ERROR()) END Que:Name = 'Smith' !Initialize key field GET(NameQue,'FirstField') !Get the matching record IF ERRORCODE() THEN STOP(ERROR()) END Que:Name = 'Jones' !Change key field PUT(NameQue,'FirstField') !Write changes to the queue IF ERRORCODE() THEN STOP(ERROR()) END **See Also:** [[next read next record in sequence .htm|NEXT]] [[previous read previous view record in sequence .htm|PREVIOUS]] [[get read a record or entry .htm|GET]] [[add add an entry .htm|ADD]] [[watch automatic concurrency check .htm|WATCH]] [[hold exclusive record access .htm|HOLD]] [[release release a held record .htm|RELEASE]] [[sort sort queue entries .htm|SORT]]