[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

OpenVMS Record Management Services Reference Manual


Previous Contents Index


$PUT

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

1The default for the RAB$B_RAC field is RAB$C_SEQ.
2This field is not supported for DECnet for OpenVMS operations.
3This option is meaningless unless you specify manual unlocking.

Table RMS-62 lists the control block fields written as output by the Put service.

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.

1On the successful completion of a Put service to a record-oriented device, the RAB$L_STV field contains the second longword of the I/O status block. See the OpenVMS I/O User's Reference Manual for details on specific devices.

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

1One of the RBF fields must contain an address and the RSZ field associated with it must contain a size.
2This field is not supported for DECnet for OpenVMS operations.

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.

RMS$_ACT RMS$_BLN RMS$_BUG
RMS$_BUG_DAP RMS$_CDA RMS$_CHK
RMS$_CONTROLC RMS$_CONTROLO RMS$_CONTROLY
RMS$_DME RMS$_DNR RMS$_DUP
RMS$_ENQ RMS$_EXT RMS$_EXT_ERR
RMS$_FAC RMS$_FTM RMS$_FUL
RMS$_IBF RMS$_IDX RMS$_IOP
RMS$_IRC RMS$_ISI RMS$_KBF
RMS$_KEY RMS$_KSZ RMS$_MRN
RMS$_NEF RMS$_NET RMS$NETBTS
RMS$_NETFAIL RMS$_NORMAL RMS$_OK_ALK
RMS$_OK_DUP RMS$_OK_IDX RMS$_OPNOTSUP
RMS$_PENDING RMS$_PLG RMS$_RAB
RMS$_RAC RMS$_RBF RMS$_RER
RMS$_REX RMS$_RHB RMS$_RLK
RMS$_RPL RMS$_RRV RMS$_RSA
RMS$_RSZ RMS$_RVU RMS$_SEQ
RMS$_SQO RMS$_STR RMS$_SUC
RMS$_SUP RMS$_SUPPORT RMS$_SYS
RMS$_TRE RMS$_WBE RMS$_WER
RMS$_WLK RMS$_WPL  


Previous Next Contents Index