Reproduced from Cartography and Geographic Information Systems, Special Issue: IMPLEMENTING THE SPATIAL DATA TRANSFER STANDARD, American Congress on Surveying and Mapping, Vol. 19, No. 5, Dec. 1992. SDTS Support Software: The FIPS 123 Function Library Robert Lazar ABSTRACT: To increase access to and use of the Spatial Data Transfer Standard (SDTS) as Federal Information Processing Standard (FIPS) 173, the U.S. Geological Survey developed software tools that support implementation of the SDTS. The most significant tool is a library of C language functions that can be called by user application programs to read and write files compliant to FIPS 123, the standard used by the SDTS for its physical file implementation. KEYWORDS: Spatial Data Transfer Standard, software library, ISO 8211, encoding, decoding Introduction The Federal Information Processing Standard Publication 123 (FIPS 123) Function Library was developed by Computer Sciences Corporation under U.S. Geological Survey (USGS) contract to support reading and writing Spatial Data Transfer Standard (SDTS) data sets. FIPS 123 is an existing standard that is used for the physical implementation of the SDTS. FIPS 123 is also known as International Organization for Standardization (ISO) 8211 and American National Standards Institute (ANSI)/ISO 8211 (American National Standards Institute, Inc., 1986). The library consists of 30 application-program-callable functions written in the ANSI standard C language. The library has been designed to be portable to multiple computer platforms. It was developed originally on personal computers using the MS DOS 3.3 operating system and the Microsoft C version 5.1 compiler. It has also been ported to Data General AVIION workstations. These workstations use the AT&T Unix operating system. The source code for the two platforms is identical, only one statement in a header file is different (U.S. Geological Survey, 1991). Library Functions Library functions include  Three functions that read FIPS 123 data descriptive records (DDR's) and three functions that read FIPS 123 data records (DR's). Records can be read by subfield, field, or the entire record.  Six similar functions that write DDR's and DR's. Records can also be written by subfield, field, or the entire record.  Functions that open and close FIPS 123 files.  Functions that allow backing up and erasing subfields, fields, and records.  "Checking" functions that return a description of the last or next subfield, field, or record read or written. For subfields, these functions return the tag, label, and format. For fields, these functions return the tag, field length, field name, field control, labels, and format. For records, these functions return the record length, leader identifier, and description of each field in the record.  Functions that initialize and end writing of FIPS 123 records. These functions allow application programs to easily write records by subfield or field. The library software handles the intricacies of formatting the FIPS 123 record, including computing the leader and directory. Table 1 lists all functions in the FIPS 123 Function Library. Using the Library for Encoding Figure 1 shows the pseudocode for a typical application program that uses the library to encode data into an SDTS file. An actual program would include much additional code to extract the data from an input data format and convert the data into SDTS and FIPS 123 constructs. The program first calls the beg123file function to open the output SDTS file, passing to the function the file name and that the file is to be opened in write mode. Beg123file returns a file pointer that is used as input to all additional functions that process the same file. The program then creates the FIPS 123 DDR, which describes the contents of the DR's. This is done by calling the beg123ddrec function to initialize the DDR, by calling the wr123ddfld function for each field, and then by calling the end123ddrec function to terminate processing of the DDR and write it to the output file. The library internally computes the leader and directory portions of the DDR when end123ddrec is called. The wr123ddfld function requires as input the field tag and the DDR field contents. These can be obtained from the specification table of part 3 of the SDTS. The application program alternatively can call the wr123ddsfld function to write by subfield instead of field or can call the wr123ddrec function to write an entire record; however, this requires more work by the application programmer because the specification table of part 3 is organized by fields. A similar process writes each DR. The beg123rec function initializes the data record. Data are added to the record by using either the wr123rec (entire record), wr123fld (a field at a time), or wr123sfld (a subfield at a time) functions. The end123rec function terminates the record, computes the leader and directory, writes the record to the output file, and frees data structures. When all records have been written to the output file, the end123file function closes the file and frees all data structures used for the file. Using the Library for Decoding Figure 2 shows the pseudocode for a typical application program that uses the library to decode data from an SDTS file. Again, the "process subfield" step can be quite involved in an actual program. The program must interpret what the data that have been read mean in the SDTS and how the data map into a source data model. The program calls the beg123file function to open the file, in this case passing a parameter that indicates that the file is being opened for reading. The rd123ddrec function reads the DDR from the file. This function loads internal data structures with the information contained in the DDR; this information is later used to interpret DR's. Although rd123ddrec returns the contents of the DDR to the application program, it is not necessary for the application programmer to decode it or directly use it. DR's can be read by subfield using the rd123sfld function, by field using the rd123fld function, or by entire record using the rd123rec function. The example shown in figure 2 reads by subfield. This may be the easiest way for an application to read DR's because the library functions handle the separation of individual subfields from fields and records. The rd123sfld function returns the data for the subfield read, the size of the data, the field tag, and leader identifier. It also returns a status code that indicates whether the subfield read is at the end of a field, end of a record, or end of the file. The chk123sfld function returns the description of the subfield. These data were read from the DDR by the rd123ddrec function and were stored in internal structures. The description includes the field tag, the subfield description (label), and subfield format. The field tag and subfield label correspond respectively to the field and subfield mnemonics contained in module definitions in part 1 of the SDTS. These mnemonics give meaning to the data: whether the data are spatial addresses (coordinates), attribute values, topological pointers, or whatever. The format is used to determine the type of data. Data may be stored either as ASCII characters or as binary data; it is necessary to use the format to interpret the data correctly. The rd123sfld and chk123sfld functions can be called for every subfield in the file. The end of file status code returned by rd123sfld can be tested to determine when the end of the file has been reached. The end123file function then closes the SDTS file. Obtaining the FIPS 123 Function Library The library is public domain software that is distributed free by the USGS. The source code is distributed so that users can recompile the software on their particular computer platform. The MicroSoft C and Data General Unix libraries used by the USGS are also distributed for users of those particular platforms. Normally the software is distributed on 3 1/2-inch DOS floppy diskettes. However, 5 1/4- inch DOS diskettes and Unix diskettes are available. The software is documented by two National Mapping Program Technical Instructions: the FIPS Pub 123 Application Programmer's Reference Manual (APRM) and the FIPS Pub 123 Function Library Software Documentation. The APRM is used by applications programmers and is included with the software. The software documentation is used by maintenance programmers and is not distributed with the software but is available upon request. To obtain the FIPS 123 Function Library, write to the following address: SDTS Software Coordinator Branch of Standards and Technology U.S. Geological Survey 526 National Center Reston, VA 22092 Phone: (703) 648-4182 Additional SDTS Software Support Tools The USGS is developing additional software tools to support implementation of the SDTS. These tools include programs to dump SDTS files into a more user-friendly format, programs to allow users to display and "browse" SDTS files prior to importing these files into their computer systems, and programs to validate SDTS files. These new programs will use the existing routines available in the FIPS 123 Function Library. REFERENCES American National Standards Institute, Inc. 1986. American National Standard for Information Systems -- Specification for a Data Descriptive File for Information Interchange, ANSI/ISO 8211-1985. U.S. Geological Survey, 1991. National Mapping Program Technical Instructions, FIPS Pub 123 Application Programmers Reference Manual (Draft version.) U.S. Department of the Interior. BIOGRAPHY Robert Lazar is a cartographer in the Branch of Standards and Technology, Office of Research, National Mapping Division, U.S. Geological Survey, 526 National Center, Reston, Virginia 22092. Any use of trade names and trademarks is for descriptive purposes only and does not constitute endorsement by the U.S. Geological Survey. Table 1. FIPS 123 library functions. Function Purpose bak123fld Backs up to the beginning of the last DR field read or written bak123rec Backs up to the beginning of the last DR read or written bak123sfld Backs up to the beginning of the last DR subfield read or written beg123ddrec Initializes a DDR for the input or output file beg123file Opens an input or output file for processing beg123rec Initializes a DR for the input or output file chk123fld Retrieves a description of the last DR field read or written chk123nfld Retrieves a description of the next DR field to be read or the last one written chk123nrec Retrieves a description of the next DR to be read or the last one written chk123nsfld Retrieves a description of the next DR subfield to be read or written chk123rec Retrieves a description of the last DR read or written chk123sfld Retrieves a description of the last DR subfield read or written end123ddrec Terminates DDR processing end123file Closes an input or output file end123rec Terminates the processing of a DR er123ddfld Erases the last DDR field written er123ddrec Erases the entire DDR written er123ddsfld Erases the last DDR subfield written rd123ddfld Reads the next DDR field rd123ddrec Reads the entire DDR rd123ddsfld Reads the next DDR subfield rd123fld Reads the next DR field rd123rec Reads the next DR rd123sfld Reads the next DR subfield wr123ddfld Writes a DDR field wr123ddrec Writes the DDR wr123ddsfld Writes a DDR subfield wr123fld Writes a DR field wr123rec Writes a DR wr123sfld Writes a DR subfield beg123file Open FIPS 123 file for write beg123ddrec Initialize data descriptive record wr123ddfld Write a data descriptive record field (call for each field) end123ddrec End data descriptive record for each data record { beg123rec Initialize data record wr123fld Write field data (call for each field) end123rec End data record } end123file Close FIPS 123 file Figure 1. Typical SDTS encoding program. beg123file Open FIPS 123 file for read rd123ddrec Read the data descriptive record, load into internal structures do { rd123sfld Read subfield chk123sfld Get subfield description: tag, label, format process subfield } while read status != end of file end123file Close FIPS 123 file Figure 2. Typical SDTS decoding program.