Program AEZCCS01 accepts a reference file, in the example below named RULES, as input and converts the formatted input data to unformatted random access file format for quick access and efficient processing in programs AEZCCS02 and AEZCCS03. Program execution is controlled by a short control data file, file CTRL01.
Given the simple task of program AEZCCS01, the program logic is straightforward. After reading the program control information from file CTRL01, each record of the specified reference data file containing AEZ productivity assessment rules is decoded and processed accordingly. The information is transferred to random access data files for use in programs AEZCCS02 and AEZCCS03.
| Unit Nr | File Name | Fileb) Type | Record Length (bytes) | Number of Recordsa) | File Size (bytes) | I/Oc) Mode |
| 5 | CTRL01 | FS | 80 | 5 | 400 | R |
| 6 | PRINTER | FS | 132 | V | - | W |
| 10 | RULES | FS | 80 | 3099 | 247920 | R |
| 11 | RND01 | UR | 192 | 1800 | 345600 | W |
| 13 | RND03 | UR | 160 | 135 | 21600 | W |
a) ‘V’ indicates a variable, district or country specific number of records.
b) FS = formatted sequential, UR = unformatted random access.
The record length and number of records of the unformatted random access files RND01 and RND03 have been calculated using the parameter constants defined in file MAXDEF.H (see Appendix B). In terms of these constants, the record length of file RND01 is equal to max(2*MCRP, 30+2*(21+MTHZ)), and the record length of file RND03 equals 8*MFGR. The values given in the table above refer to the Kenya Case Study where the number of crops is MCRP=96, the number of thermal zones is MTHZ=9, and parameter constant MFGR=20. Similarly, the number of records can be expressed in terms of these parameter constants that are used to make the computer programs more flexible and more easily adaptable to other environments.
| Name : | AEZCCS01 | |
| Type: | Main program | |
| Purpose : | Convert formatted reference/rules input data on crop cycles and suitability rules to unformatted random access files for use in land productivity assessment. | |
| Called by : | none | |
| Calls to : | CLR2BI, ERROR, MATCH, MAXLGP | |
| Arguments : | none | |
| Box Ref. : | 1.1 | |
| Name : | CLR2BI (buf, n, val) | |
| Type: | subroutine | |
| Arguments : | integer*20, integer, integer | |
| buf | data buffer to be zeroed | |
| n | number of elements in buffer | |
| val | value to be assigned to data buffer elements | |
| Purpose : | initialize a 2-byte integer array buf of specified length n to a given value val. | |
| Called by : | MAIN | |
| Calls to : | none | |
| Box Ref. : | none | |
| Name : | ERROR (ityp, buf, ifatal) | |
| Type: | subroutine | |
| Arguments : | integer, integer | |
| ityp | error code | |
| buf | line buffer where error occurred | |
| ifatal | error level | |
| Purpose : | Display an error message. | |
| Called by : | MAIN | |
| Calls to : | none | |
| Box Ref. : | none | |
| Name : | MATCH (ch1, ch2, n) | |
| Type: | integer*2 function | |
| Arguments : | character* 1, character*l(), integer | |
| ch1 | character to be matched | |
| ch2 | string to be searched for matching character | |
| n | number of characters in ch2 to be tested | |
| Purpose : | Test n characters of string ch2 to match character chl. | |
| Called by : | MAIN | |
| Calls to : | none | |
| Box Ref. : | none | |
| Name : | MAXLGP (LGPbuf) | |
| Type: | integer*2 function | |
| Arguments : | integer*20 | |
| LGPbuf : | character to be matched | |
| NPurpose : | Test n characters of string ch2 to match character ch1. | |
| Called by : | MAIN | |
| Calls to : | none | |
| Box Ref. : | none | |
TABLE 2.1
Control input data for program AEZCCS01
| Card Nr. | Variable name | Data file contents | Format specification |
| 01 | FNINP | RULES | (A50) |
| 02 | FNRND1 | RND01I | (A50) |
| 03 | FNRND3 | RND03I | (A50) |
| 04 | ITECH | 2 | (A1) |
| 05 | IDEBUG | 0 | (I1) |
Each AEZ-CCS program is controlled by a short input data file which is usually read from standard input. Table 2.1 shows an example used to run program AEZCCS01 setting up table information for intermediate level of input, where
| FNINP | = | name of file (including full path) containing AEZ-CCS productivity assessment rules. |
| FNRND1 | = | name of unformatted random access file (including full path) containing converted productivity assessment rules for use in programs AEZCCS02 and AEZCCS03. |
| FNRND3 | = | name of unformatted random access file (including full path) containing converted fallow requirement rules for use in program AEZCCS03. |
| ITECH | = | 1-digit input level designator : |
| 1 = low input level | ||
| 2 = intermediate input level | ||
| 3 = high input level | ||
| IDEBUG | = | 1-digit debug level indicator; should be zero under normal operation |
Land productivity assessment as discussed here is based on the calculation of various multipliers referring to specific attributes of the land inventory entry under consideration. The rules controlling the necessary calculation steps are contained in a rule definition file, named RULES. Each record in the file can be identified by a two character code. So far, eleven different record types have been included in the file :
CC - Cards : Cash crop LGP allocation rules
CN - Cards : Crop cycle requirement rules
CR - Cards : Coarse material rating rules
CY - Cards : Crop yield by LGP
FR - Cards : Fallow land requirements
FY - Cards : Fluvisol LGP rules
PL - Cards : Pattern LGP rules
PP - Cards : Pattern proportion rules
PR - Cards : Phase rules
SR - Cards : Soil suitability rating
TR - Cards : Thermal zone suitability rating rules
The sequence of records in the rule definition file is not important, except that crop cycle requirement rules, i.e. records starting with CN, have to be included at the very beginning of the file. In the following the record format of each of these card types is described. Short illustrative examples can be found in Appendix C.
In the current version of the AEZCCS programs the crop production modules for some of the cash-crops have not been fully elaborated. To ensure appropriate allocation of cash-crops under a wide possible range of climatic conditions the CC-cards specify cash-crop LGP allocation rules. For all possible combinations of pattern code and LGP code, each cash-crop is assigned a 1-digit rating, representing decreasing suitability, or 0 in case of unsuitable conditions.
| Card Position | Contents |
| 1 – 2 | card lable |
| 3 – 5 | country code |
| 6 – 8 | 3-digit crop code |
| 9 | input level code |
| 10 – 11 | pattern code |
| 12 – 26 | 1-digit suitability rating by LGP (MLGP = 15 entries in the Kenya Case Study) |
The CN-cards introduce the crops to be considered in the calculations of the productivity assessment program. The current implementation of the computer program allows for a maximum of 130 crops. Each crop is defined in terms of a 3-digit crop code, average crop cycle length in days, a 20-character text label, and minimum and maximum crop cycle requirements.
| Card Position | Contents |
| 1 – 2 | card label |
| 3 – 5 | country code |
| 6 – 8 | 3-digit crop code |
| 9 – 11 | average crop cycle length (days) |
| 12 – 31 | character*20 crop text label |
| 32 – 34 | minimum crop cycle requirement (days) |
| 35 – 38 | maximum crop cycle requirement (days) |
| 39 – 41 | sequential crop number |
| 43 | crop mask type: l=annual crops, 2=perennial crops, 3=pastures, trees |
| 44 | crop type index: l=cereals, 2=pulses, 3=roots, 4=perennial food crops, 5=other cash crops, 6=not used, U7=pastures, 8=trees with nitrogen fixing abilities, 9=trees without nitrogen fixing abilities |
| crops with index > 3 cannot enter sequential crop combinations | |
| 45 | slope cultivation association table look-up index: l=dry-land crops, 2=wetland crops, 3=other crops, pastures |
| 46 | inter-cropping eligibility indicator |
| 47 | water-stress table look-up index |
| 48 – 51 | yield conversion factor from dry weight to fresh weight |
| 53 | vegetation cover factor rule index |
| 54 | vegetation cover percentage rule index: l=annual crops, 2=perennial crops, 3=trees |
| 55 | vegetation cover percentage table look-up index, perennial crops |
| 56 – 58 | percentage of LAI at residual stage in relation to LAI at harvesting stage |
| 59 – 61 | crop stage distribution (percent): establishment |
| 62 – 64 | crop stage distribution (percent): early vegetative |
| 65 – 67 | crop stage distribution (percent): late vegetative |
| 68 – 70 | crop stage distribution (percent): maturation |
| 71 – 73 | crop specific multiplier K in crop cover percentage function |
| 74 – 76 | maximum leaf area index (times 10), annual crops |
The CR-cards describe the crop specific suitability rating in relation to a particular soil texture attribute, called coarse material code. For all possible coarse material codes each crop is assigned a rating 1 to 4 representing suitability quartiles, or 0 in case of lack of suitability.
| Card Position | Contents |
| 1 – 2 | card label |
| 3 – 5 | country code |
| 6 | input level code |
| 7 – 12 | character*6 coarse material description label |
| 13 – 14 | coarse material code |
| 15 – 79 | coarse material suitability rating by crop 1 to MCPR |
In the Kenya Case Study MCRP=96 crops have been considered (see Appendix A). Hence, two lines had to be used per coarse material code, the first line containing ratings for crops 1 to 65, the second line for crops 66 to 96.
The CY-cards specify for each crop constraint-free attainable yields by input level and length of growing period zone. The yield figures do not reflect soil related constraints or climatic constraints other than those implied by the LGP code. Temperature requirements of crops or water stress during the growing period are not dealt with in the CY-cards.
| Card Position | Contents |
| 1 – 2 | card label |
| 3 – 5 | country code |
| 6 – 8 | crop code |
| 9 | input level code |
| 10 – 13 | maximum crop yield (10 kg dry weight per ha) |
| 14 – 17 | crop yield in LGP 1 |
| 18 – 21 | crop yield in LGP 2 |
| . | |
| . | |
| . | |
| 70 – 73 | crop yield in LGP 15*) |
FR-cards specify fallow land requirement rules, i.e. the number of years out of a hundred year cycle during which the land is not available for crop cultivation. In the AEZ-CCS methodology, the rest period requirement depends on climate (thermal zone, LGP code), crop type, soil type and input level. In the Kenya Case Study, climatic conditions have been classified into MFGR=20 categories, crop types into four classes. Each record contains all the fallow period requirement coefficients in relation to one particular soil type and crop class at low level of input. The calculation of fallow requirements at input levels other than low is related to the low input fallow requirements.
| Card Position | Contents |
| 1 – 2 | card label |
| 3 – 5 | country code |
| 6 | input level code |
| 7 – 9 | character*3 soil unit label |
| 10 – 12 | soil unit code |
| 13 | card sequence number by crop class |
| 14 – 16 | requirement parameter THZ 1, LGP 60–89 days |
| 17 – 19 | requirement parameter THZ 1, LGP 90–119 days |
| 20 – 22 | requirement parameter THZ 1, LGP 120–179 days |
| 23 – 25 | requirement parameter THZ 1, LGP 180–269 days |
| 26 – 28 | requirement parameter THZ 1, LGP 270 < days |
| 29 – 31 | requirement parameter THZ 2/3, LGP 60–89 days |
| 32 – 34 | requirement parameter THZ 2/3, LGP 90–119 days |
| . | |
| . | |
| 71 – 73 | requirement parameter THZ 6/7/8/9, LGP 270 < days |
The FY-cards describe the crop specific suitability rating by LGP in relation to cultivation on Fluvisols. For each input level each crop is assigned a maximum yield and for all possible LGP codes a 1-digit rating representing decreasing suitability, or 0 in case of lack of suitability.
| Card Position | Contents |
| 1 – 2 | card label |
| 3 – 5 | country code |
| 6 – 8 | crop code |
| 9 | input level code |
| 10 – 13 | maximum crop yield (10kg dry weight / ha) |
| 14 – 28 | 1-digit suitability rating, by LGP 1 to MLGP* |
The PL-cards describe the relationship between inventorized dominant LGP codes and pattern codes by specifying the length of individual component length of growing periods in different pattern groups, e.g in bi-modal rainfall, pattern group L2, an annual length of growing period of 300 – 329 days (LGP code 12) refers to two growing seasons with 180 – 209 days (component LGP code 08) and 120–149 days (component LGP code 06) respectively.
| Card Position | Contents |
| 1 – 2 | card label |
| 3 – 5 | country code |
| 6 – 7 | pattern code |
| 8 – 9 | LGP code |
| 10 – 11 | pattern component LGP LH |
| 12 – 13 | pattern component LGP L1 |
| 14 – 15 | pattern component LGP L2 |
| 16 – 17 | pattern component LGP L21 |
| 18 – 19 | pattern component LGP L |
| 20 – 21 | pattern component LGP L3 |
| 22 – 23 | pattern component LGP L31 |
| 24 – 25 | pattern component LGP L32 |
| 26 – 27 | pattern component LGP L33 |
| 28 – 29 | pattern component LGP L4 |
| 30 – 31 | pattern component LGP L41 |
| 32 – 33 | pattern component LGP L42 |
| 34 – 35 | pattern component LGP L43 |
| 36 – 37 | pattern component LGP L44 |
| 38 – 39 | pattern component LGP LD |
PP-cards relate pattern codes to the probability of occurrence of seasonal rainfall conditions.
| Card Position | Contents |
| 1 – 2 | card label |
| 3 – 5 | country code |
| 6 – 7 | rainfall pattern code |
| 8 – 10 | probability of occurrence of humid pattern LH |
| 11 – 13 | probability of occurrence of uni-modal pattern L1 |
| 14 – 16 | probability of occurrence of bi-modal pattern L2 |
| 17 – 19 | probability of occurrence of tri-modal pattern L3 |
| 20 – 22 | probability of occurrence of pattern L4 |
| 23 – 25 | probability of occurrence of dry pattern LD |
The PR-cards describe the crop specific suitability rating in relation to a particular soil phase attribute. For all possible soil phase combination codes each crop is assigned a 1-digit rating (1 to 4 in the Kenya Case Study) representing decreasing suitability, or 0 in case of unsuitable conditions.
| Card Position | Contents |
| 1 – 2 | card label |
| 3 – 5 | country code |
| 6 | input level code |
| 7 – 12 | character*6 phase combination label |
| 13 – 14 | phase combination code |
| 15 – 79 | 1-digit soil phase suitability rating by crop 1 to MCRP* |
The SR-cards describe the crop specific suitability rating in relation to a particular soil type. For all possible soil unit codes each crop is assigned a 1-digit rating (1 to 4 in the Kenya Case Study) representing decreasing suitability, or 0 in case of unsuitable soil conditions
| Card Position | Contents |
| 1 – 2 | card label |
| 3 – 5 | country code |
| 6 | input level code |
| 7 – 11 | soil unit label |
| 12 – 14 | character* 5 soil unit code |
| 15 – 79 | 1-digit soil suitability rating by crop 1 to MCRP*) |
The TR-cards describe the crop specific suitability rating in relation to a particular temperature regime. For each crop a TR-record is required containing a 1-digit suitability rating for each possible thermal zone code (1 to 9 in the Kenya Case Study), or 0 in case of non-suitable thermal zones.
| Card Position | Contents |
| 1 – 2 | card label |
| 3 – 5 | country code |
| 6 | input level code (not used) |
| 7 – 9 | 3-digit crop code |
| 10 – 18 | 1-digit thermal zone suitability rating, by THZ 1 to THZ 9 |
