Document revision date: 15 July 2002

The Put service inserts a record into a file.

RAB64 Users RAB64 can replace the RAB or RAB prefix wherever it is used with the Put service on OpenVMS Alpha systems.

Format

SYS$PUT rab [,[err] [,suc]]

RETURNS

OpenVMS usage:	cond_value
type:	longword
access:	write only
mechanism:	by value

The value is returned in symbolic offset RAB$L_STS. Symbolic offset RAB$L_STV may contain additional status information.

Arguments

rab

OpenVMS usage:	rab
type:	longword (unsigned)
access:	modify
mechanism:	by reference

RAB control block whose contents are to be used as indirect arguments for the Put service call. The rab argument is the address of the RAB control block.

err

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by reference

AST-level error completion routine that the service invokes if the operation is unsuccessful. The err argument is the address of the entry mask of this user-written completion routine.

suc

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by reference

AST-level success completion routine that the service invokes if the operation is successful. The suc argument is the address of the entry mask of this user-written completion routine.

Description

The Put service usually adds records to the logical end of a sequential file. For relative files, it may add records to the logical end of the file or it may insert new records in cells formerly occupied by deleted records. RMS directs the Put service where to insert the record using the contents of the record's primary key field.

Inserting Records into Sequential Files

When using sequential record access mode to process sequential files, you usually insert records at the end of the file only. The records to be inserted cannot be larger than the maximum length that was specified when the file was created.

You can use random access by relative record number mode and the update-if record-processing option (RAB$V_UIF) to insert fixed-length records into a sequential file residing on a disk device.

RMS also provides for establishing the logical end of the file when two or more processes are doing shared write operations. For example, assume that processes A and B are sharing a sequential file and each process is putting data into the file. Process A puts a record at the end of the file and intends to put another record at the new end-of-file location. However, before process A can put the next record in the file, process B gains access to the file and puts a record at the end of the file. In order to ensure that the next record from process A does not overwrite the record just inserted by process B, RMS updates process A's write pointer to the new end-of-file position; that is, the location immediately following the location of process B's record.

The truncate-on-put option (RAB$V_TPT) can be used with sequential files. This option lets you add records at locations other than the logical end of the file. When you add a record using the truncate-on-put option, the file is automatically truncated, effectively deleting all data between the new record (logical end of the file) and the physical end of the file. If you try to use this option without having truncate access, RMS rejects the operation and issues a file access error (RMS$_FAC).

For stream format files, RMS writes the contents of the user's buffer into the file beginning at the current entry position. If the last byte in the buffer is not a terminator, RMS adds the appropriate terminator. For stream format, the terminator is CRLF (carriage return character followed immediately by a line feed character).

Mailboxes may be used to synchronize activity between processes. Usually, a Put service to a mailbox does not conclude until another accessor reads the record. If you select the timeout option (RAB$V_TMO) and specify a timeout period of 0, the Put service does not wait for another accessor to read the record.

At the conclusion of the Put service, the RAB$L_STV field contains the process identification (PID) of the process that read the record.

Inserting Records into Relative Files

When processing relative files, you can use either sequential or random access by key mode. Records cannot be larger than the size specified at file creation time, and the record's relative record number must not exceed the maximum record number established for the file. Usually, if the target record cell for a Put service contains a record, a record-already-exists error (RMS$_REX) is returned as the completion status (RAB$L_STS). If you specify the update-if (RAB$V_UIF) record option, RMS overwrites the existing record instead of returning an error message. If you try to use the update-if option but do not have update access, RMS rejects the operation and issues a file access error (RMS$_FAC).

Inserting Records into Indexed Files

In an indexed file, you can use sequential access or random access by key mode. When sequential access is used to insert records, the primary key value of the record to be inserted must be consistent with the specified sort order of the file. That is, the key must be greater than or equal to the primary value of the previous record if ascending sort order is specified. If descending sort order is specified, the key must be less than or equal to the primary key value of the previous record.

The records cannot be larger than the size established when the file was created if a maximum length was specified. Each record written must contain a primary key, but the records do not have to contain alternate keys. If alternate keys are partially or completely missing because of the record length limitation, RMS does not make an entry for the record in the associated alternate index. Put services to an indexed file do not require a separate key value or key of reference. By examining the contents of the primary key in the record, RMS determines where to insert the record.

When inserting a record into an indexed file, RMS compares the key values in the record with the key values of records previously inserted into the file to determine whether the new record's key value duplicates any existing key values. If the record duplicates a key value in an index where duplication is not allowed, RMS rejects the operation with an RMS$_DUP error code. Where duplicate keys are allowed, RMS inserts the record.

Records with duplicate keys are inserted in chronological order; that is, RMS inserts each record having duplicate keys at the end of a "chain" of identically keyed records so that newer records are stored closer to the end of the file regardless of sort order.

If you specify the update-if (RAB$V_UIF) option when duplicates are not allowed on the primary key, RMS overwrites the existing record with the same primary key value, rather than returning a duplicate record error (RMS$_DUP). This gives the appearance of an Update service being performed on the existing record. Alternate key values are modified to reflect the newly inserted record.

To use the RAB$V_UIF option, you must have update access to the file. If update access to the file is not permitted, the Put service (which becomes an Update service when this option is selected) fails, and RMS returns a file access error (RMS$_FAC).

Be careful when invoking the Put service with the RAB$V_UIF option and automatic record locking for a shared file. The Put service, unlike the Update service, momentarily releases record locks previously applied by a Get or Find service, until the Put service is converted into an Update service. This could allow another record stream to delete or update the record between the invocation of the Put service and the conversion to an Update service. To avoid this complication, you should use the Update service instead of the Put service with the update-if option to update an existing record in a file-sharing situation.

The record address field and the record size field are required inputs to the Put service. Some Put service options may require additional fields. The traditional address and size fields are RAB$L_RBF and RAB$W_RSZ. However, OpenVMS Alpha users have the option to code -1 in the RAB64$L_RBF field to direct the Put service to use the values in the alternative fields, RAB64$PQ_RBF and RAB64$Q_RSZ. The RAB64$PQ_RBF field can hold either a 64-bit address or a 32-bit address sign-extended to 64 bits.

A successful Put service returns the record file address (RFA) in the RAB$W_RFA field.

RAB Control Block Fields

Table RMS-61 lists the control block fields read as input by the Put service. For additional information on the fields accessed by this service, see Part 2.

Table RMS-61 Put Service RAB Input Fields

Field Name	Option or XAB Type	Description
RAB$W_ISI		Internal stream identifier (required).
RAB$L_KBF		Key buffer address (used as input only with random access by relative record number mode).
RAB$B_KSZ		Key size (used only if RAB$B_RAC is KEY and the file is a relative file).
RAB$B_RAC		Record access mode (SEQ, KEY) 1.
RAB$L_RBF		Record buffer address.
RAB$L_RHB		Record header buffer (for variable with fixed control records only).
RAB$W_RSZ		Record size.
RAB$L_ROP		Record-processing options.
	RAB$V_ASY	Asynchronous: performs Put services asynchronously.
	RAB$V_CCO 2	Cancel Ctrl/O: guarantees that terminal output is not discarded if the operator enters Ctrl/O.
	RAB$V_LOA	Load: specifies that buckets are to be loaded according to the fill size established at file creation time.
	RAB$V_REA 3	Lock for read: allows other users read access to the record. This is not valid for relative files.
	RAB$V_RLK 3	Read of locked record allowed: specifies that a record locked for modification can be read by other users.
	RAB$V_TMO 2	Timeout: indicates that the content of the timeout period field (RAB$B_TMO) is to be used.
	RAB$V_TPT	Truncate-on-put: specifies that a Put service with a sequentially-accessed record can occur at any point in the file, truncating the file at that point.
	RAB$V_UIF	Update-if: converts a Put service to a record that already exists to an Update service.
	RAB$V_ULK	Manual unlocking: specifies that records cannot be unlocked automatically.
	RAB$V_WBH	Write behind: two buffers are allocated to allow multibuffering.
	RAB$V_WAT	Wait: if the record is locked, wait until it is available (for relative files only).
RAB$B_TMO 2		Timeout period: a value of 0 indicates that RMS should not wait to complete a Put service (for mailbox devices only).

Table RMS-62 Put Service RAB Output Fields

Field Name	Description
RAB$L_BKT	Bucket code: set to the relative record number for sequential access to relative files.
RAB$W_RFA	Record file address.
RAB$L_STS	Completion status code (also returned in register 0).
RAB$L_STV	Status value 1.

RAB64 Control Block Fields (Alpha Only)

Table RMS-63 lists the Alpha-only RAB64 control block fields read as input by the Put service. These fields are comparable to the RAB fields described in Table RMS-61. For additional information on the fields accessed by this service, see Part 2.

Table RMS-63 Put Service RAB64 Input Fields (Alpha Only)

Field Name	Description
RAB64$B_BLN	This field must be initialized to RAB64$C_BLN64 in order for RAB64 fields to be used.
RAB64$W_ISI	Internal stream identifier (required). Equates to RAB$W_ISI.
RAB64$L_KBF	Key buffer address. This field must contain -1 if you want to use RAB64$PQ_KBF. For 32-bit addressing, this field equates to RAB$L_KBF (see Table RMS-61).
RAB64$PQ_KBF	Key buffer 64-bit address (used if RAB64$L_KBF contains -1 ). This field can hold either a 64-bit address or a 32-bit address sign-extended to 64 bits.
RAB64$B_KSZ	Key buffer size. Equates to RAB$B_KSZ (see Table RMS-61).
RAB64$B_RAC	Record access mode. Equates to RAB$B_RAC (see Table RMS-61).
RAB64$L_RBF 1	Record buffer address. This field must contain -1 if you want to use RAB64$PQ_RBF. For 32-bit addressing, this field equates to RAB$L_RBF.
RAB64$PQ_RBF 1	Record buffer 64-bit address (used if RAB64$L_RBF contains -1 ). This field can hold either a 64-bit address or a 32-bit address sign-extended to 64 bits.
RAB64$L_RHB	Record header buffer. This field must contain -1 if you want to use RAB64$PQ_RHB. For 32-bit addressing, this field equates to RAB$L_RHB (see Table RMS-61).
RAB64$PQ_RHB	Record header buffer 64-bit address (used if RAB64$L_RHB contains -1 ). This field can hold either a 64-bit address or a 32-bit address sign-extended to 64 bits.
RAB64$W_RSZ 1	Record buffer size. This field is ignored in favor of RAB64$Q_RSZ if RAB64$L_RBF contains -1 . Otherwise, this field equates to RAB$W_RSZ.
RAB64$Q_RSZ 1	Record buffer size. This field must be used when RAB64$L_RBF contains -1 and a value is specified in RAB64$PQ_RBF.
RAB64$L_ROP	Record-processing options. Equates to RAB$L_ROP and options described in Table RMS-61. Options are identical except for the RAB64 prefix; for example, option RAB64$V_ASY equates to RAB$V_ASY.
RAB64$B_TMO 2	Timeout period. Equates to RAB$B_TMO (see Table RMS-61).

Table RMS-64 lists the Alpha-only RAB64 control block fields written as output by the Put service. These fields are comparable to the RAB fields described in Table RMS-62.

Table RMS-64 Put Service RAB64 Output Fields (Alpha Only)

Field Name	Description
RAB64$L_BKT	Bucket code. Equates to RAB$L_BKT (see Table RMS-62).
RAB64$W_RFA	Record file address. Equates to RAB$W_RFA.
RAB64$L_STS	Completion status code. Equates to RAB$L_STS (see Table RMS-62).
RAB64$L_STV	Status value. Equates to RAB$L_STV (see Table RMS-62).

Condition Values Returned

The following condition values can be returned. Use the Help Message utility to access online message descriptions. For more information about interpreting condition values, see Section 2.4.

	privacy and legal statement
4523PRO_031.HTML