USDA AMS Cotton Program 

National Database 

Detailed Overview 

USDA’s Agricultural Marketing Service (AMS) Cotton Program maintains a National Database (NDB) 

in Memphis, Tennessee for owner access to cotton classification data. The NDB is a computerized

telecommunications system which allows owners or authorized agents of owners to retrieve classing 

data from the current crop and/or the previous four crops. The NDB stores classing information from all 

AMS cotton classing facilities. 

How the National Database Works

The NDB is a batch processing system. Before connecting to the system, customers must create a 

request file on their computer containing user logon information and ranges of bale numbers they are 

requesting. The request file is uploaded and processed automatically upon a successful connection. A 

data file is then returned to the customer’s computer. The data file is a text file with fixed length fields 

that can be easily imported or parsed by most programs. Software to process the retrieved records is not

provided by the Cotton Program. The software can be obtained from other sources or developed by the 

customer. If needed, the Cotton Program provides a simple print program (printams) that can be used to 

print the retrieved records. 

 

What Data is Available

All Form 1 Classing Office data is available from the NDB. The NDB stores data by gin code and gin 

bale number (e.g. Permanent Bale Identifier or PBI) for the current crop year and previous four crop 

years. Two types of requests can be made from the NDB. The first request is for data only and the 

second request is for a Form R. 

The official cotton quality measurements include the official color grade, extraneous matter, remarks, 

leaf grade, length, strength, micronaire, length uniformity, color (instrument color grade, quadrant, Rd 

and +b) and trash on an individual bale basis. A more detailed description of the quality measurements 

can be accessed at the following web address:

www.ams.usda.gov/cotton/understand.htm

The Request File

The request file contains user logon information, optional Form R header information and a list of 

requested bale(s). The request file name is always c:\natdb (no extension). The NDB User Manual, 

which is supplied when an account is established, contains detailed file format information. 
The first line in the request file always contains the 5 digit user number, password, owner flag, Form R 

flag and the not found flag. 

For data only requests (non Form R), the additional lines contain PBI information (specified in bale 

number ranges) and a crop year flag (Current or Old). When Old crop is requested, the program will 

automatically search up to four years of Old crop databases, beginning with the most recent, before 

specifying the record as Not Found (NF). A Current crop request will only search the Current crop 

database. You can easily discern the crop year of the PBI record by examining the Date Classed on 

either the data file or the Form-R. 

For Form R requests, the additional lines contain several header lines and a list of requested bales. The 

header lines contain name and address information of the current owner and warehouse of the bales to 

be printed. For each requested bale, the PBI, corresponding warehouse bale number and crop year flag 

must be supplied for the Form R. 

The Cotton Program provides a program (balerang) that can be used to create the request file. Most 

customers have the ability to create the request file automatically from their software. 

Example of the c:\natdb for Normal Telecommunications: 

54321TESTUSERYNY User 54321, Password TESTUSER, (Owner, Form R, NF) flags 

9999900000010000010C Bale range of 1 to 10 for gin code 99999 (Current Crop) 

9999800000250000025O Bale range of 25 to 25 for gin code 99998 (Old Crop) 

9999900000300000040C 

Connecting to the National Database

In order to retrieve data from the system, callers must install software provided by the Cotton Program. 

Two versions of the software are currently available. The Internet version is provided at no cost and is 

the most widely used version. A Windows version is available for customers who do not have access to 

the Internet or want a backup connection method. The one-time cost for the Windows software is 

$40.00. Cotton Program software, operating instructions and technical support are supplied with both 

versions. Both versions of the software require access to the root (c:\) folder for file transfers. The 

Internet version requires a Java enabled browser (Internet Explorer or Netscape) with 128 bit SSL 

encryption capability. 

The request file is uploaded and processed automatically upon a successful connection. A data file is 

then returned to the customer’s computer. 

Data File

The returned data file is always c:\ams01 (no extension) and contains the requested quality information 

for bale record(s) found. The data file is a text file with fixed length fields that can be easily imported or 

parsed by most programs. Detailed file layouts are included with the software for the request file 

(natdb) and the returned data file (ams01). The data file is returned for both data only and Form R 

requests. Since the ams01 file is overlaid each time a connection is made, customers must process data 
in the ams01 file before connecting to the NDB again. Data not processed will be lost (overlaid) at the 

time of the next download. The cost of providing data is $0.05 per record found. 

Example of the c:\ams01 file until June 30, 2005: 

 

9999900000082004070200000000000323231 23.43 31376092 01 099 7910-0665 

9999900000092004070200000000000423231 23.6311 31376092 02 100 7710-1190 

9999900000532004070200000000000523332 23.6411 32272099 04 104 7710-1585 

NF999990000054C 

NF999990000055C 

9999900000562004070200000000000323132 22.53 31376091 01 098 8010-0745 

Example of the c:\ams01 file beginning July 1, 2005: 

99999000000820040702000000003232312343000031376209201099791100-0665 

99999000000920040702000000004232312363110031376309202100774101-1190 

99999000005320040702000000005233322364110032272109904104773101-1585 

NF999990000054C 

NF999990000055C 

99999000005620040702000000003231322253000031376409101098801100-0745 

The lines beginning with “NF” indicate requested records that were not found. NF records are returned 

unless the optional NF flag in set to “N” in the logon record. 

Form R (Printed Report)

Customers may also obtain a certified classification document (Form R) from the National Database in 

addition to telecommunications. Customers select which quality factors are printed on each Form R by 

setting the appropriate flag in the request file. The data file (c:\ams01) is returned immediately while the 

Form R reports are mailed out daily. The cost of the Form R includes shipping the report by U. S. mail. 

If overnight service is requested, the customer must supply their FEDEX account number to cover 

shipping charges. The cost of providing the Form R is $0.15 per bale, with a minimum fee of $5.00 per 

page. A full page contains 50 records ($7.50). 

Example of a Form R report: 

FORM CN-358 UNITED STATES DEPARTMENT OF AGRICULTURE MEMO. NO. 89-00000 

 7-1-1998 AGRICULTURAL MARKETING SERVICE PAGE 1 

********* WAREHOUSE ********** COTTON PROGRAM NATIONAL DATABASE *********** OWNER ************ 

Test Warehouse MEMPHIS, TENNESSEE **************** Test Owner 

3275 Appling Road FORM R CLASSIFICATION MEMORANDUM * OWNERS MARKS * 3275 Appling Road 

Memphis, TN 38133 * Test Mark * Memphis, TN 38133 

************************************************************************************************************************************ 

THE OWNER CERTIFIES THAT THE WAREHOUSE BALE NUMBERS AND CORRESPONDING GIN BALE NUMBERS IDENTIFY THE SAME BALES OF COTTON. 

***************************** QUALITY FACTORS DESIGNATED "NA" ARE OMITTED AT THE REQUEST OF THE OWNER ****************************** 

WAREHOUSE GIN GIN DATE BALES OFF COL LENGTH LEAF EXT./ - HVI COLOR - LENGTH LENGTH RECORD 

 BALE CODE BALE CLASSED MODULE MO/TR GRADE (32ND) MIKE STRENGTH GRADE REMARKS GRADE RD +B TRASH (100TH) UNIFORM TYPE 

 0000001 99001 9999999 12/22/2004 S 21 38 44 35.4 2 21-1 80 091 01 118 82 U O 

 0000002 99001 9999998 12/22/2004 S 21 38 45 35.3 2 21-1 80 091 01 119 82 U O 

 0000003 99001 9999997 12/22/2004 S 11 37 44 36.3 2 11-2 81 090 01 116 82 U O 

 0000004 99001 9999996 12/22/2004 S 11 37 44 34.0 2 11-1 82 087 02 117 84 U O 

 0000005 99001 9999995 12/22/2004 S 11 38 45 33.4 2 11-2 82 086 02 119 83 U O 

************************************************************************************************************************************ 

PURSUANT TO THE REGULATIONS OF THE U. S. DEPARTMENT OF AGRICULTURE FOR COTTON CLASSIFICATION (7 CFR 28.910) IT IS CERTIFIED THAT 

THE DATA SHOWN ABOVE CORRESPONDS TO THE OFFICIAL U. S. D. A. CLASSIFICATION OF THE SAMPLES. 

COLOR GRADE AND HVI COLOR DATA ARE VALID FOR ONLY ONE YEAR FROM THE DATE OF CLASSIFICATION. **Signature of** 

 DATE ISSUED - 12/15/2004 CHIEF, COTTON PROGRAM IT STAFF 
Establishing a National Database User Account

To establish an account on the NDB, customers must complete the “National Database Application” 

form and send the completed form to the Cotton Program’s IT Staff by fax, mail or email. If the 

Windows version of the software is requested, the $40.00 license fee must be included with the 

application. Customers may also complete the “National Database Credit Card Information” form if 

they want to pay for software and/or usage fees by credit card. 

Upon receipt of the completed application, an ID number and password will be assigned to the account. 

Installation Instructions, file formats, NDB User Manual and software (Windows only) will be sent after 

the account is established. If the Internet version is selected, a website address will be supplied for the 

download of the software. 

All active accounts are billed monthly. If any data is downloaded during the month, the account is 

subject to a $5.00 minimum charge. 

Contact Information: 

USDA AMS Cotton Program

Information Technology Staff 

3275 Appling Road 

Memphis, TN 38133 

Phone: (901) 384-3007 

Fax: (901) 384-3035 

Email: CottonIT@usda.gov 

United States Department of Agriculture 

Agricultural Marketing Service 

Cotton Program 

Version 2004-1