Adapters > Using the Adapter for RMS > Associating an RMS Data Source to a Master File

Associating an RMS Data Source to a Master File

Topics:

When to Use an Access File With an RMS Data Source
File and Record Locking
File Locking and the Interface to RMS
Record Locking
Handling Locked Records During Table Read Request

How to:

Specify a Physical File Location Using DATASET= and the RMS Data Source
Associate an RMS Data Source in an Access File

You can associate an RMS file to a Master File using the following methods:

DATASET attribute in a Master File. The DATASET attribute in a Master File specifies the physical or app location for the data source to be allocated. This attribute is used at the file declaration level of the Master File, as described in DATASET. The synonym creation facility uses the DATASET attribute in the Master File. For details, see Specify a Physical File Location for the RMS Data Source.
RMSFILE attribute in an Access File. You can use either the RMSFILE attribute or a DATESET attribute if you are creating Master and Access Files from scratch using a text editor. If both DATASET and RMSFILE are declared, DATASET takes precedence. For details, see Associate an RMS Data Source in an Access File.
FILEDEF command. An explicit allocation (FILEDEF) for the data file is checked for when a DATASET or RMSFILE attribute is detected in a Master File. If an explicit allocation is found, the DATASET and RMSFILE attributes are ignored and the allocation is used.
If the data file name is not allocated with a FILEDEF, an internal command is issued to perform the allocation using the DATASET or RMSFILE values. This allocation is stored temporarily and is released when a new Master File is used or when the session terminates.

If both attributes exist, DATASET takes precedence over RMSFILE. However, an explicit FILEDEF command takes precedence over both the DATASET and RMSFILE attributes.

Syntax: How to Specify a Physical File Location Using DATASET= and the RMS Data Source

The DATASET attribute is used at the file declaration level of the Master File. The syntax is

{DATASET|DATA}={'filename'|app/filename.[extension]}

where:

filename: Is the platform-dependent physical name of the data source. In a prior release, the physical name was required to be in single quotes. This is still valid syntax, but not required. A direct logical name such as MYQ2DATA: is also valid but must include the colon character, so it is distinct from an app-based name.
app/filename[.extension]: Is an app-based logical name of the data source. The default extension when no extension is supplied is .dat.

Note: If a DATASET allocation is in effect, a CHECK FILE command must be issued in order to override it by an explicit allocation command. The CHECK FILE command will deallocate the allocation created by DATASET. The default extension when no extension is supplied is .dat.

Example: Allocating an RMS Data Source Using the DATASET Attribute

The following example illustrates how to allocate an RMS data source on the file declaration level and for an alternate index:

FILE=EXERVSM1, SUFFIX=RMS,$
DATASET='MYDISK:[mydata.sample]testdata.dat',$
SEGNAME=ROOT , SEGTYPE=S0,$
 GROUP=KEY1  , ALIAS=KEY , FORMAT=A4, ACTUAL=A4 ,$
  FIELD=FLD1 , ALIAS=F1  , FORMAT=A4, ACTUAL=A4 ,$
  FIELD=FLD2 , ALIAS=F2  , FORMAT=A4, ACTUAL=A4 ,$
  FIELD=FLD3 , ALIAS=DD1 , FORMAT=A4, ACTUAL=A4 ,$
  FIELD=FLD4 , ALIAS=F4  , FORMAT=A4, ACTUAL=A4 ,$
  FIELD=FLD5 , ALIAS=F5  , FORMAT=A4, ACTUAL=A4 ,$
  FIELD=FLD6 , ALIAS=F6  , FORMAT=A4, ACTUAL=A4 ,$
  FIELD=FLD7 , ALIAS=F7  , FORMAT=A4, ACTUAL=A4 ,$

Syntax: How to Associate an RMS Data Source in an Access File

The Access File has the following format

RMSFILE   = {'filename'|app/filename.[extension]},
[ACCESS   = {SHARED|READONLY},]
[LOCKMODE = {SKIP|KEEP} ,]
[STATMODE = {EXCEPTIONS|ON|OFF},] $

where:

filename: Is the platform-dependent physical name of the data source. In a prior release, the physical name was required to be in single quotes. This is still valid syntax, but not required. A direct logical name such as MYQ2DATA: is also valid, but must include the colon character, so it is distinct from an app-based name. The default extension when no extension is supplied is .dat.
app/filename.[extension: Is an app-based logical name of the data source. The default extension when no extension is supplied is .dat.

Example: Overriding DATASET and RMSFILE With a FILEDEF Command

You can override the DATASET value in the Master File or the RMSFILE declaration in the Access File with a FILEDEF command. The FILEDEF can be done locally within a procedure (before accessing the file) or within the profile. For example,

FILEDEF rmsfile DISK {'filename'|app/filename.[extension]}

where:

rmsfile: Is the logical metadata reference name matching the physical file name.
filename: Is the platform-dependent physical name of the data source. In a prior release, the physical name was required to be in single quotes. This is still valid syntax, but not required. A direct logical name such as MYQ2DATA: is also valid, but must include the colon character, so it is distinct from an app-based name. The default extension when no extension is supplied is .dat
app/filename.[extension: Is an app-based logical name of the data source. The default extension when no extension is supplied is .dat.

When to Use an Access File With an RMS Data Source

An Access File is optional for an RMS data source if the DATASET attribute is used in the Master File and if WRITE access is not required. However, even in those instances, you may wish to have an Access File to specify ACCESS, LOCKMODE, and STATMODE for RMS files:

The ACCESS attribute can have a value of SHARED for read/write access, or READONLY for Read access. READONLY is the default setting when no explicit ACCESS parameter is present.
The LOCKMODE attribute is primarily for retrieval (TABLE / SQL SELECT) only, but does have an effect on MODIFY / SQL UPDATE, so a site may want to consider separate Master Files for this purpose. LOCKMODE can have a value of REJECT, SKIP or KEEP. LOCKMODE not declared is the equivalent of REJECT.
STATMODE attribute can have a value of EXCEPTIONS, ON, or OFF. EXCEPTIONS is the default and displays a message when locked records are encountered. ON allows a message to occur (whether or not locked records are encountered), and OFF suppresses locking messages.

See File and Record Locking for more information on ACCESS, LOCKMODE, and STATMODE. For related information, see Handling Locked Records During Table Read Request.

File and Record Locking

This topic describes features that enable a developer to control file and record locking. Lock conflict, or contention, can occur at file level or record level. File contention is caused by incompatible access by two or more processes. Record contention is caused when a requested lock is incompatible with any existing locks on the record.

The following terms summarize the types of access allowed to RMS files and records:

Access Type	Description
Read Access	Provides users with access to a file and the records in the file for actions that make no alterations. Read can use any access mode (dependent on site needs) for the actions that are defined in the following tables.
Read/Write Access	Provides users with access to a file and the records in the file for actions that make alterations to records, add records, or delete records. Read/write access requires the use of SHARED as the access mode. All other modes do not support WRITE operations.

File Locking and the Interface to RMS

When your request attempts to open an RMS file, the Access Parameter within the Access File determines what you can do at a file level with the RMS file, and what actions others can take while you have the file open.

When a request attempts to open an RMS file, the Access Parameter determines which type of access to use. If the Access Parameter specification is incompatible with another process' access to the file, the procedure fails because it is not able to open the file. Additionally, if the file is opened for read, but a subsequent write is attempted, it will fail due to an inappropriate access mode.

Depending on how a file is opened, as specified by the Access Parameter, subsequent opens are limited as follows:

		Processes by Others
		READONLY	SHARED	PROTECTED	EXCLUSIVE
Processes by Server Users	READONLY	Allowed	Allowed	Allowed	Denied
Processes by Server Users	SHARED	Allowed	Allowed	Allowed when SHAREd process is doing read-access operation.	Denied

This table describes user access and file sharing options used in response to the following Access File options for the Access Parameter.

Access Parameter	User Access	File Sharing to Other Processes
READONLY	Read	Read and Write
SHARED	Read and Write	Read and Write

Record Locking

RMS requests are no-lock for each record retrieved for READ operations during TABLE or SELECT. RMS operations for UPDATE and DELETE will take a lock on the record with SYS$GET for the duration of the operation and will check the return code status. An INSERT checks for existence, does SYS$PUT and checks the return code status.

Handling Locked Records During Table Read Request

Topics:

LOCKMODE
STATMODE

RMS files can be accessed while they are simultaneously accessed by other programs.

For example, the file might be in use by another program that is maintaining the data by adding, deleting, or updating records.

A lock on a record affects the ability of the server to access a record depending on whether the request is for READ (TABLE or SELECT) or for an UPDATE or DELETE operation.

RMS files can be accessed while they are simultaneously accessed by other programs. For instance, the file might be in use by another program that is maintaining it by adding, deleting, or updating records.

When a READ operation is rejected due to a lock conflict by another process (and the Access File does not have LOCKMODE, or LOCKMODE is set to REJECT), the request is aborted and the following message is displayed:

(FOC1325) RMS READ LOCK ABORT ERROR

You can override this behavior on a file-by-file basis using the LOCKMODE and STATMODE options in the Access File. LOCKMODE and STATMODE do not apply to WRITE requests such as UPDATE or DELETE, but they do affect general behavior.

LOCKMODE

Topics:

LOCKMODE=KEEP Wait Time

The LOCKMODE parameter controls server behavior when a locked record is encountered. LOCKMODE has three valid values (REJECT, KEEP, and SKIP, as described below), and respective behaviors. The default when LOCKMODE is not explicitly declared is REJECT.

LOCKMODE READ Behaviors.

LOCKMODE = REJECT (or Not Declared). On READ, when a specific record read operation is rejected due to a lock conflict by another process, the whole request (SELECT or TABLE) is aborted and the following message is displayed:
```
(FOC1325) RMS ABORT : %RMS-E-RLK, target record currently locked by another stream
```
Records retrieved before the lock is encountered may have already been sent to the client (displayed) and should be discarded.
LOCKMODE = KEEP. On READ, retrieves all records, including locked records and completes the request.
LOCKMODE = SKIP. On READ, retrieves all records, except locked records and completes the request.

LOCKMODE UPDATE and DELETE Behaviors.

LOCKMODE = REJECT (or Not Declared). On UPDATE or DELETE, when an operation is rejected due to a lock conflict by another process, the request is immediately aborted and the following message is displayed:
```
(FOC1325) RMS ABORT : %RMS-E-RLK, target record currently locked by another stream
(FOC1303) RMS RECORD NOT FOUND filename
```
LOCKMODE = KEEP.
- On UPDATE or DELETE, when a record is locked due to a lock conflict by another process, the request is waited with a delay cycle (10 seconds by default). If the record frees up during the period the record is processed, otherwise it is rejected as a timeout with the following message:
```
(FOC1301) RMS TIME OUT ERROR: {file}/%RMS-W-TMO, timeout period expired
```
  The delay period is 10 seconds and is adjustable (see LOCKMODE=KEEP Wait Time). The delay is set at the RMS file open time and can not be adjusted on a record by record basis. If the locked record has actually changed since original retrieval the request will fail with:
```
(FOC526)TRANS     1 INVALID OTHER USER CHANGED filename
```
  Failure recovery logic may be written into an application (that is, simple retry, recompute and retry, or continue) on the assumption that the record will be unlocked on the re-attempt. It is up to the application developer to write any such recovery logic, there are no automatic retries in this scenario.
LOCKMODE = SKIP. On UPDATE or DELETE, when an operation is rejected due to a lock conflict by another process, the request is immediately rejected and the following message is displayed:
```
 (FOC415)TRANS     1 REJECTED  NOMATCH filename
```

LOCKMODE does not affect INSERT operations because a lock cannot exist on a record that does not exist. The adapter will, appropriately, reject a record if another process inserts the same record before the adapter does, it is just not a LOCKMODE failure.

LOCKMODE=KEEP Wait Time

LOCKMODE=KEEP has a built-in 10 second delay upon encountering a record under UPDATE or DELETE modes. The purpose is to enable a developer to write recovery logic for UPDATE in case a record changed between when it was initially accessed and the actual adapter UPDATE attempt, but to not let the re-attempt happen so quickly that the record would still be locked.

The LOCKMODE=KEEP delay time is also settable using the following syntax.

ENGINE RMS SET WAIT_LOCKED n

where:

n: Is the wait time in number of seconds.

The delay can never be set to zero (use an alternate no-delay LOCKMODE value for zero). Specifying the value zero (0) results in the default value of 10.

STATMODE

STATMODE controls whether or not a message is sent to the client program about retrieved records. STATMODE has three settings:

ON
To receive a message giving the statistics of data retrieval, set STATMODE to ON in the Access File. The message displays, in addition to the report request, after data retrieval is complete. For example:
```
STATMODE = ON
```
A FOC1320 message displays when no locked records are encountered. For example:
```
(FOC1320) RMS STATS  :(SEGCAR   ) Reads = 1, Skips = 0, Keeps = 0
```
If LOCKMODE is set to KEEP a FOC1324 message displays. For example:
```
(FOC1324) RMS KEEP   :(SEGCAR   ) Reads = 1, Skips = 2, Keeps = 0
```
If LOCKMODE is set to SKIP, a FOC1322 message displays. For example:
```
(FOC1322) RMS SKIP   :(SEGCAR   ) Reads = 1, Skips = 0, Keeps = 2
```
OFF
Set the STATMODE to OFF if no messages are to be sent when locked records are encountered. The client application will not have any indication whether or not locked records were encountered during record retrieval.
EXCEPTIONS
To receive a message giving the statistics of data retrieval, only if locked records are encountered, set the STATMODE to EXCEPTIONS. The message displays, in addition to the report request, after data retrieval is complete. No message displays if no locked records are encountered during retrieval. For example:
```
STATMODE = EXCEPTIONS
```
If LOCKMODE is set to KEEP a FOC1324 message displays. For example:
```
(FOC1324) RMS KEEP   :(SEGCAR   ) Reads = 1, Skips = 2, Keeps = 0
```
If LOCKMODE is set to SKIP, in addition to the report output, a FOC1322 message displays. For example:
```
(FOC1322) RMS SKIP   :(SEGCAR   ) Reads = 1, Skips = 0, Keeps = 2
```

Example: Syntax Samples for an Access File

The following is an example of a Remote Node:

RMSFILE=HOST1::DISK$PROG:[PROD.INFO]EMPINFO.DAT,ACCESS=SHARED,$

The following is an example of a Full Path as defined by a logical and a file name:

RMSFILE=DATADIR:PERSON.DAT,ACCESS=READONLY,$

The following is an example of a Logical Name:

RMSFILE=MYLOGICAL:,ACCESS=SHARED,$

The following is an example of a Full Path on a file using LOCKMODE and STATMODE:

RMSFILE=DISK100:[DATA]PERSON.DAT,ACCESS=READONLY,LOCKMODE=SKIP,
  STATMODE=OFF,$

	WebFOCUS

Feedback