26 File Servers
This chapter contains these topics:
-
Section 26.3, "What are the Advantages of Using a File Server?"
-
Section 26.4, "What are the Disadvantages of Using a File Server?"
26.1 About File Servers
-
Allow you to enhance the processing time of your program.
-
Ease the maintenance of your programs by making your system more modular.
Eventually, every program should perform database functions using either a file server or a functional server.
Note:
All logical files are accessed through servers by their based-on file. Embedded in one server, there may be many access paths available.26.2 What is a File Server?
A file server, or I/O server, is a server that performs RPG database operations.
This type of server has no effect on program logic, but it isolates the actual database from the application program. Once you implement a file server into a program, the file specification is no longer required.
26.2.1 Types of File Servers
There are three types of file servers you can use:
| File Server | Description |
|---|---|
| XS | Input-Only/Caching Servers
They can be used in place of a simple CHAIN operation for input only. You may request descriptions only, or the entire record. They provide caching logic to decrease physical I/O for duplicate requests. |
| XF | Input/Output File Servers
They allow you to replace all RPG database operation codes for a given file with program calls. They can perform such functions as READ, CHAIN, and SETLL to a file. |
| X | Special Scrub & Edit Servers
They can accept cost center, account numbers, numeric fields, or a data string in any valid data entry or file format, convert them to any format, validate the existence of the master record, and optionally pass the master record or the scrubbed data back to the calling program. |
26.3 What are the Advantages of Using a File Server?
The advantages of using a file server are
-
Minimized maintenance of your software
-
Ability to change a physical file without having to make changes to application programs that use the file, or even having to recompile them
-
Use of versions in future releases to allow programs from a previous release to run against a changed database
-
Smoother transition from an old database to a new database. Instead of applying all new programs, you will only have to apply a new set of file servers
-
Ability to implement one file server at a time without affecting the rest of your system
26.4 What are the Disadvantages of Using a File Server?
The disadvantages are:
-
A file server is minutely slower because you are performing an external call to the server from your program
-
File server programs tend to be large
File servers are designed to perform all database functions that can be performed directly.
26.5 How Does a File Server Function?
A file server performs all the interfaces between a program and file. After you load the control parameters, which contain information about the record you are retrieving, the file server converts the control parameters and returns a record to the program.
If you plan to use any of the file server programs and you are asking them to return the database record, you must use the record image /COPY member that the corresponding I/O server uses. The /COPY member has the following naming convention:
I(file name) (release level).
For example: The copy member for the F0101 record image should appear as:
I/COPY JDECPY, I010171
Note:
Some technical file servers (X9800E, X0005) have a /COPY member with the naming convention:I(file name)(special character)
I/COPY JDECPY, I0005U
A file server may be called with two parameters:
Figure 26-1 Two Parameters for Calling a File Server
Description of "Figure 26-1 Two Parameters for Calling a File Server"
| PARM | Description |
|---|---|
| PS@@1 | Contains all of the control parameters. It is contained in copy module I00XFSRV, and it is common to all file servers. |
| I(file name) | Contains the record image for updates and writes specific for each I/O server. It is an exact duplicate of the record image. It is contained in the copy module I(file name) (release level). |
26.6 What Are Control Parameters?
The parameter PS@@1 is a Data Structure which contains all the control parameters for the file server. All control parameters, except the format name, are cleared every time the server returns control to the calling program. You must set the parameter values every time the server is called unless you are satisfied with the default values.
| PARM (Length) | Description |
|---|---|
| @@ACCS (1) | The type of access to the file. The valid values are K for Keyed access (default), R for relative record number access and S for sequential access (DREAM Writer). |
| @@OPER (10) | The operation to be performed to the file. The valid values are presented below:
CHAIN Chain by key list or RRN CLOSE Close the access path DELET Delete current record or by key or RRN EXIST Test existence of record by key OPEN Open access path (optional) READ Read next record READE Read next equal key READP Read previous record REDPE Read previous equal key SETGT Set greater than key SETHV Set greater than with *HIVAL SETLL Set lower limit by key SETLV Set lower limit with *LOVAL UPDAT Update locked record UPDATC Update current record WRITE Write new record UNLCK Unlock current record |
| @@LOCK (1) | Whether you do or do not want to lock the record. The valid values are Y to lock the record (default) or N to not lock the record.
Note: This parameter is only valid for chain and read operations, and is ignored for all other operations. You should set it to N when reading records not to be updated. |
| @@CHGR (1) | Servers allow records to be read without lock and then be updated (UPDATC). In this situation, the record will be re-read before it is updated and if it has changed since it was last read, action will have to be taken. This parameter determines what that action will be. The valid values are:
N – Do not update the record. A return code (RC) is returned and it comes up to the program to determine what action to take. (default) O – Overlay the changed record with the values you are currently updating. This will cause the changes made by the other user to be lost. W – Call the Changed Record Window (P0000U) that will prompt you for what action to take. Use this option with interactive programs only. |
| @@KLST (10) | The key list that will be used for access. The calling program does not specify a logical file so that the application program is isolated from any database changes. A value must be specified unless you are accessing the file by relative record number or sequentially (@@ACCS = R or S).
Note: The server maintains status information for each access path, so multiple paths can be accessed through the server in one program. The @@KLST parameter determines which access path is affected by the current call to the server. |
| @@KNUM (5,0) | Specifies how many key fields in the list will be used for the current operation. This allows you to perform a read equal by a partial key. The valid values are 1 through the number of fields in the key, and blank for operations not requiring a key. |
| @@FMT (10) | Specifies the release level the program is expecting. This field does not get cleared upon returning from the server, so it can be set once in S999. |
| @@#RRN (9,0) | The relative record number for RRN access. |
| I (file name) | Record image for updates and writes. This parameter is optional for OPEN, CLOSE, DELET, SETHV, SETLV, and UNLCK operations. |
Access paths are opened automatically when the first operation is performed. Therefore, it is not necessary to call the server with the OPEN operation.
A server normally remains active as long as the calling program is active. If you know you will need a server for only a limited period of time and do not want it taking up space in the PAG, you can call the server the @@OPER parameter blank, this causes the server to return and end.
26.7 What Are Returned Parameters?
When the file server returns the record to the program, there are several parameters associated with it.
| PARM (Length) | Description |
|---|---|
| @@IOR(3) | The I/O return code.
The possible values are: blank – No errors NF – Record not found NE – Not equal for a READE operation EOF – End of file EQ – Equal for a SETLL operation BOF – Beginning of file RL – Record Locked, could not read RC – Record changed YES – Record found NO – Record not found ERR – Error, check error fields for explanation |
| @@ERR (10) | Short description of the cause of the problem (invalid, reclock, error, required, deleted, chgrec). |
| @@ERRS (10) | The subject causing the error. The value could be a parameter (KLST), an operation (OPEN), or a file name (Fxxxx). Used in combination with @ERR gives a good idea of what happened. The application program will generally only use @@IOR. @@ERR and @@ERRS are most useful for debugging purposes. |
| @@#RRN (9,0) | Returns the relative record number of the record just read (both input and output). |
| I (filename) | Returns an exact duplicate of the record image (both input and output). |
26.8 Implementing a File Server
The following are generally the steps needed to set up a file server in a program. Some programs may differ.
-
Remove F-spec line for file being accessed through the server, and replace it with a comment mentioning access through the server.
-
Add clear statement in S999 (CLEAR PS@@1). You can optionally set @@FMT to the JD Edwards base release value ("A73" or "A81") so it does not have to be set on every call.
-
Copy in I-spec copy module I00XFSRV.
-
Copy in I-spec copy module for the required server, following the naming convention: I(file name) (release level). For example, I010171.
-
Code call to server for each database access. Naming convention for server is X(file name). For example, XF0101 for F0101 and any of its logicals.
-
Load control parameters
-
Load record image if a write or update
-
Call the server
-
Check the return code
-
-
Remove any open statements and key lists for this file from S999 in the calling program.
-
Remove any output specifications dealing with EXCPT unlock statements at the bottom of the program. The server will handle all of the unlock and lock operations.
Note:
When reading sequentially (@@ACCS = S) through the physical file or through a DREAM Writer based-on file that is overridden to the physical, some operations are not available. Do not use: CHAIN, EXIST, READE, REDPE, UPDATC, SETLL, SETGT, SETHV, SETLV. Since UPDATC is not available and you are going to update a record, you need to read with lock.If the file you are accessing though the server is the DREAM Writer based on file, the Open Query Options on the DREAM Writer Additional Parameters screen need to be changed. Change all of the "Open for xxxxx" parameters to "Y" on the DW Additional Parameters screen.
26.9 Searching for Key Lists
When converting programs to use the file servers, make note of what logical files are being accessed, and what mode (update or input) and what each of the defined key lists for those access paths represent. There are some servers with information in the F93201 which is accessed by the following process. Otherwise, using the Where Used function on a file entry in SVR may show which "X" (server) programs access a particular file.
-
Look up the corresponding server key list name using P93KL (fast path, KL).
-
Search for the format name for files that are accessed in the program.
-
Replace each instance of file access code with a call to the server with the correct parameters.
26.10 Tips when Using File Servers
The following tips can help when using file servers:
-
When converting a program to use the file servers, always set the @@LOCK parameter to "N" when reading records through an access path that the program uses to open for input only.
The reason for this is that all access paths are open for update in the server. This can cause record lock problems when a program opens multiple paths into the same file. Correct use of the @@LOCK parameter solves these problems.
-
Some programs may be doing a CHAIN or EXCPT to unlock a record. Instead of replacing it with a CHAIN through the server, take advantage of the UNLCK operation. Performing an UNLCK on a file that does not have a record locked does not produce an error.
-
Some programs perform a SETLL to validate that a record exists. The new operation EXIST is provided to handle this function. It returns a YES or NO in return code (@@IOR).
-
There is only one instance in which a particular file server is active in your job, so if one program calls another program that accesses the file through the same access path, they are actually sharing the same open data path. If it is possible that a call to another program could relocate a file pointer that could error out the program, it would be a good idea to save the keys and reset the pointer (CHAIN or SETLL) upon returning.
26.11 Commonly Used File Servers
The following is a list of commonly used file servers:
| File Server | Description | Notes |
|---|---|---|
| X0005 | User Defined Codes Server | Retrieve Only |
| X0006 | Retrieve Cost Center Master | Retrieve & Scrub |
| XF0006 | Cost Center I/O | Add/Change/Delete |
| X0010 | Automatic Next Numbering | Retrieve & Increment |
| X9203 | DD Alpha Description | Retrieve Only |
| X9800E | Data Dictionary Info | Editing Info |
| XF0101 | Address Book I/O | Add/Change/Delete |
| XS0101LA | Address Book | Retrieve Only |
| X0901 | Account Master | Retrieve & Formats |
| XF0901 | Account Master I/O | Add/Change/Delete |
| X41LOCN | Location Format | |
| X41LOT | Lot Number Assignment | |
| X41DUP | Lot Master Duplicate | Edits |
| X4101 | Item Master | Retrieve & Edit |
| X4108 | Lot Master Update | Creates & Updates |
| X4111 | Write to Item Ledger | Writes Only |
| XF4111 | CARDEX I/O | Retrieve Only |
| XF42119 | Sales History I/O | Add/Change/Delete |
| XF42199 | Sales Detail Ledger I/O | Add/Change/Delete |
| XF43199 | Purchasing History I/O | Add/Change/Delete |