Defining Functions › Database Functions › Internal Database Functions and PHY Access Paths › Internal Database Functions

Internal Database Functions

This section describes what happens when the following internal database functions are created over physical (PHY) access paths: Retrieve object (RTVOBJ), Change object (CHGOBJ), Delete object (DLTOBJ), and Create object (CRTOBJ).

Retrieve object (RTVOBJ)

A RTVOBJ created over a PHY access path has one *Relative record number (RRN) parameter by default:

This *Relative record number parameter can be used as a "key" to the physical file as follows:

RRN as a Restrictor Parameter (I, B, or N) to a PHY RTVOBJ—If the RRN for a RTVOBJ function built over a PHY access path is a Restrictor parameter, only the record with RRN equal to the parameter value is read.

RRN as a Positioner Parameter (I, B, or N) to a PHY RTVOBJ—If the RRN for a RTVOBJ function built over a PHY access path is a Positioner parameter, only records with RRN greater than or equal to the parameter value are read.

RRN as an Output Parameter from a PHY RTVOBJ—If the RRN for a RTVOBJ function built over a PHY access path is an Output parameter, all records in the access path are read, starting with record 1. The RRN of the last record read from the file is passed as the parameter value.

RRN as a Neither Parameter to a PHY RTVOBJ—If the RRN for a RTVOBJ function built over a PHY access path is a Neither parameter, the RRN first used to access the file is the current value of the Neither parameter. The Neither parameter is accessible from the RTVOBJ in the PAR context. Although the parameter is initialized to 1 in the RTVOBJ, it can be changed to any numeric value in the User Exit Point USER: Initialize routine. The value following that User Exit Point is used to access the file initially.

Deleting the RRN Parameter to a PHY RTVOBJ—If the default RRN parameter is deleted, two outcomes are possible:

• If USER: Process data record User Point contains user logic, all records in the access path starting with record 1 are read.
• If USER: Process data record User Point does not contain user logic, only record 1 is read.

Note: You can add other parameters besides RRN to PHY RTVOBJ functions, but RRN must be passed first.

The following is a quick reference table for processing the *Relative record number parameter:

• Depends on processing in the USER: Process data record User Exit Point.

Change object (CHGOBJ)

In a normal CHGOBJ, the processing includes these steps:

1. USER: Processing before data read.

2. Load key fields to record format.

3. Access file to check if record exists.

4. USER: Processing if data record not found.

5. If record not found, send error message and quit.

6. If record locked, send error message and quit.

7. USER: Processing after data read.

8. Load non-key fields to record format.

9. USER: Processing before data update.

10. Update record.

11. If update failed, send error message and quit.

12. USER: Processing after data update.

In a CHGOBJ built over a PHY access path, the processing includes these steps:

1. Load key and non-key fields to record format.

2. USER: Processing before data update.

3. Update record.

4. If update failed, send error message and quit.

5. USER: Processing after data update.

The following notes apply to these situations:

• The pre-update file access is not generated. This is normally generated as an RPG CHAIN or as a COBOL READ statement.
• Any action diagram code in the following User Points is ignored, and no code is generated for them:
  • USER: Processing before data read
  • USER: Processing if data record not found
  • USER: Processing after data read
• A CHGOBJ created over a PHY access path can be attached only to a RTVOBJ built over the same PHY access path. This is because of the i OS requirement that a record to be changed must have been read previously.

Delete object (DLTOBJ)

In a normal DLTOBJ, the processing includes these steps:

1. USER: Processing before data update.

2. Access file to check if record still exists.

3. If record already deleted, send error message and quit.

If record locked, send error message and quit.

5. Delete record.

6. If delete failed, send error message and quit.

7. USER: Processing after data update.

In a DLTOBJ built over a PHY access path, the processing includes these steps:

1. USER: Processing before data update.

2. Delete record.

3. If delete failed, send error message and quit.

4. USER: Processing after data update.

The following notes apply to these situations:

• A DLTOBJ created over a PHY access path is created with no parameters. You must ensure that the record to be deleted was read in a RTVOBJ built over the same PHY access path. Thus, the DLTOBJ should be inserted only in the USER: Process data record User Exit Point in the RTVOBJ.
• The pre-delete file access is removed. This is normally generated as an RPG CHAIN or as a COBOL READ statement.
• Any code in the USER: Processing if data record already exists User Point is ignored.
• A DLTOBJ built over a PHY access path can be attached only to a RTVOBJ built over the same PHY access path.

Create object (CRTOBJ)

In a normal CRTOBJ, the processing includes these steps:

1. Load parameters to record format.

2. USER: Processing before data update.

3. Access file to check if record already exists.

4. USER: Processing if data record already exists.

5. If record already exists, send error message and quit.

6. Write record.

7. USER: Processing if data update error.

8. If write failed, send error message and quit.

9. USER: Processing after data update

In a CRTOBJ built over a PHY access path, the processing includes these steps:

1. Load parameters to record format.

2. USER: Processing before data update.

3. Write record.

4. USER: Processing if data update error.

5. If write failed, send error message and quit.

6. USER: Processing after data update.

The following notes apply to these situations:

• The pre-create file access is removed.
• Any code in the USER: Processing if data record already exists User Point is ignored.
• A CRTOBJ built over a PHY access path cannot be used in any function that also contains a RTVOBJ built over the same PHY access path. This is because the file definition requirements of a PHY access path used for CRTOBJ are different from those used for CHGOBJ, DLTOBJ, or RTVOBJ. However, the Action Diagram Editor registers an error only if you attempt to attach the CRTOBJ to a RTVOBJ directly. If you attach a CRTOBJ to, for example, an EXCEXTFUN that also contains a PHY RTVOBJ, the Editor does not register an error, but the function compilation will fail.

Using Functions Built Over PHY Access Paths

This is a quick reference table with information about functions built over PHY access paths:

Consider the following points when using functions built over PHY access paths:

• Because some error checking has been removed from these functions, the application designer must ensure that applications using these functions do not run at the same time as other functions that use these files. Otherwise, locks may be placed on records that these functions need to read.
• CHGOBJ and DLTOBJ functions built over a PHY access path can be used only in a RTVOBJ built over the same PHY access path. This ensures that the record to be changed or deleted has just been read in the RTVOBJ.
• A CRTOBJ function built over a PHY access path can be used only in a function that does not contain a RTVOBJ, CHGOBJ, or DLTOBJ built over the same PHY access path. We suggest that you create an Execute external function (EXCEXTFUN) with the same parameters as the CRTOBJ, include only the CRTOBJ in that function, and access the PHY CRTOBJ by using that function.
• Although the generators create code differently for the RTVOBJ, CHGOBJ, DLTOBJ, and CRTOBJ functions, the action diagram for each function does not change. This may cause confusion, because User Points are visible in the action diagram and statements can be entered in them, but those User Points may not be generated.