Welcome to jBASE's new documentation site! Many answers to your questions can be found by searching the Knowledgebase or viewing the jBASE Documentation. We also have a Google Group for peer discussion about jBASE. If you are unable to find the information you are looking for, jBASE Support will be glad to assist in resolving your technical problems. Enjoy and please provide comments and feedback .

How can we help you?

PARTITION ALGORITHM

Overview 

Each distributed file uses a partition algorithm to determine in which part file a record belongs. The partition algorithm is specified by using the create-distrib command . All part files belonging to a distributed file use the same partition algorithm. 

There are two methods for defining the partition algorithm, the system defined method and the user-defined method. The partition algorithm uses the record ID (or part of the record ID) to distribute the record to the appropriate part file.

 

System Partition Algorithm

When a distributed file is created it is automatically set to use the system partition algorithm. The create-distrib command is used to set the partition algorithm. When using the system partition method, jBASE assumes that the record ID will be in the form:

create-distrib <PartNumber> <Delimiter> <RecordID>

Where:

  • PartNumber is an integer which determines the part file to which the record is written. 
  • Delimiter can be any character except a system delimiter (AM, VM, SVM). The default delimiter is a dash (-).
  • RecordID is the actual item-ID of the record. In a ‘hashed’ file type, this determines the group to which the record is written.


The following example sets (or changes) the distributed file DISTREGION to use the system partition algorithm. A dash (-) will be used as the delimiter between the part number and the record ID:

create-distrib -pSYSTEM,- DISTREGION


 

User-defined Partition Algorithm

The user-defined method provides the greatest flexibility when the need to determine which part file a record belongs is not based on an integer value (although it could be used for that purpose as well). The user-defined method is implemented by writing a jBC subroutine which determines the part number, and then setting the distributed file to use the subroutine as the partition algorithm. As an example, a distributed file called DISTCUST has 5 part files and the first character of each ID determines which part file the record belongs.

We will use the following jBC subroutine as the partition algorithm:

SUBROUTINE DistCustSub (Reserved, Key, PartNo)
    EQU Otherwise TO 1
    * Extract the first character from the Key
    FirstChar = Key[1,1]
    * Now determine the PartNo based on FirstChar
    BEGIN CASE
        CASE FirstChar = "N"; * North
            PartNo = 1
        CASE FirstChar = "E"; * East
            PartNo = 2
        CASE FirstChar = "W"; * West
            PartNo = 3
        CASE FirstChar = "S"; * South
            PartNo = 4
        CASE Otherwise; * Invalid condition; isolate for later review
            PartNo = 99
    END CASE
RETURN

Compile and catalog the subroutine. Ensure that the subroutine is accessible via the JBCOBJECTLIST environment variable.

The subroutine is called each time a record is read from or written to the DISTCUST distributed file. The subroutine must support 3 arguments:

Argument
Description
Reserved
This parameter is reserved for future enhancements and should not be altered within the context of the subroutine.
Key
This is the record ID. It must be constructed in the application program prior to READing or WRITEing the record from/to the distributed file. Do not alter this argument, use it only as a source.
PartNo
This must be assigned by the subroutine and must return a valid part number.


It can be noted from the example that the part numbers consist of 1, 2, 3, 4 and 99. This illustrates an important feature. It is not a requirement that the part numbers be sequential or continuous. This could be used to allow additional part files to be added to the distributed file collection without the necessity of renumbering.

Take special care when writing this subroutine to account for all possibilities. If for any reason the PartNo cannot be determined, either a READ_ERROR or WRITE_ERROR will be noticed at the point of failure. Here is one such example where there are 11 part files. The part number is determined based on the last character of the key, the last character is assumed to be numeric but, if it's not, it will be placed in the 11th part file:


SUBROUTINE distsub(reserved, key, partno)
    lastchar = key[-1,1]
        IF NUM(lastchar) THEN
            partno = lastchar
            IF partno = 0 THEN partno = 10
        END ELSE
            partno = 11
        END
RETURN


Can you spot the error?

The fatal flaw is if the subroutine ever encounters an item-id of 'null'. A null item-id is considered numeric, hence partno will be set to 'null'. A better way to code this would be:

SUBROUTINE distsub(reserved, key, partno)
    lastchar = key[-1,1]
    IF lastchar >= 0 AND lastchar <= 9 THEN
        partno = lastchar
        IF partno = 0 THEN partno = 10
    END ELSE
        partno = 11
    END
RETURN

This subroutine takes the 'explicit' approach and does not make assumptions about what form the data will be in.

To set (or change) the distributed file to use the user-defined partition algorithm, the create-distrib command may be used. For example, to set the DISTCUST distributed file to use the DistCustSub subroutine:

create-distrib -pUSER,DistCustSub DISTCUST

When compared to the system partition algorithm, the user-defined partition method incurs a small performance penalty when calling the jBC subroutine. The exact cost of this is highly dependent on how easily the part number is resolved within the subroutine.


Back to DISTRIBUTED FILES

Was this article helpful?