WPCgH  
      2       B   V   [   Z           #| h          2cpi (M) Lt T d d d ,    wld p   @ ~rQ @HP LaserJet IIID                     HPLASIII.PRS d p   @ ~rQ ,\,y@#| h           2    Z   M  	             v     HP LaserJet III                      HPLASIII.PRS x 
   @   ,\,yX@a8Document g        Document Style  Style                                       X X`	`	  `	

 2 <  p   Q  k     k   ,       a4Document g        Document Style  Style                                      .  a6Document g        Document Style  Style                                    G  X  

a5Document g        Document Style  Style                                   }    X (#

a2Document g        Document Style  Style                                  < o  
   ?                    A.        

 2   v   n  t        X  	     a7Document g        Document Style  Style                                   y    X  X`	`	 (#`	

Bibliogrphy          Bibliography                                             :   X 
 (#

a1Right Par         Right-Aligned Paragraph Numbers                        : ` S  @                   I.  
  X (#

a2Right Par         Right-Aligned Paragraph Numbers                        	C  	   @`	                  A.    `	`	 (#`	

 2 	  
        n       
     a3Document g        Document Style  Style                                  
B 
 b 
   ?                     1.        
a3Right Par         Right-Aligned Paragraph Numbers                        L ! 
   `	`	 @P
                  1.  `	`	   (#

a4Right Par         Right-Aligned Paragraph Numbers                        U  j   `	`	  @                  a.    `	 (#

a5Right Par         Right-Aligned Paragraph Numbers                        
_ o    `	`	   @h                  (1)    hh# (#h

 2      	     
     X     1  a6Right Par         Right-Aligned Paragraph Numbers                        h     `	`	   hh# @$                  (a)  hh#  ( (#

a7Right Par         Right-Aligned Paragraph Numbers                        p fJ    `	`	   hh# ( @*                  i)  (  h- (#

a8Right Par         Right-Aligned Paragraph Numbers                        y W" 3!   `	`	   hh# ( - @p/                  a)  -  pp2 (#p

a1Document g        Document Style  Style                                  X q q
    
   l   ^)                       I.           ׃

 2 h  +  /
     Z     Z       Doc Init             Initialize Document Style                                  
 
               0*0*    I. A. 1. a.(1)(a) i) a)                 I. 1. A. a.(1)(a) i) a)                                     Document g                                           Tech Init             Initialize Technical Style                              .  
k    I. A. 1. a.(1)(a) i) a)                 1 .1 .1 .1 .1 .1 .1 .1                                      Technical                                            a5Technical         Technical Document Style                               ) W D                   (1)  .  a6Technical         Technical Document Style                               )  D                   (a)  .   2 W          H            a2Technical         Technical Document Style                               < 6  
   ?                    A.        

 a3Technical         Technical Document Style                               9 W g 
   2                    1.        
 a4Technical         Technical Document Style                               8 bv {    2                     a.        
 a1Technical         Technical Document Style                               F ! < 
   ?                         I.           

  2 o                      a7Technical         Technical Document Style                               ( @ D                   i)  .  a8Technical         Technical Document Style                               (  D                   a)  .  Pleading              Header for numbered pleading paper                     P@  n                         $]        X    X`	hp x (#%'0*,.8135@8:<H?A                                         y    *                    d       d d                                                                         y y    *                    d       d d                                                                         y 

HH 1

HH 2

HH 3

HH 4

HH 5

HH 6

HH 7

HH 8

HH 9

H 10

H 11

H 12

H 13

H 14

H 15

H 16

H 17

H 18

H 19

H 20

H 21

H 22

H 23

H 24

H 25

H 26

H 27

H 28	 + 	 ӋCourier 10cpi Prestige Elite 12cpi (D) Prestige Elite 12cpi (M) Prestige Elite 12cpi Bold (D) Prestige Elite 12cpi Italic (D) CG Times (Scalable) Univers (Scalable) Univers Bold (Scalable) Line Draw 12cpi (Full-PE)  2  ,        L    "   ^  '   "  m'^!.22YN!!!2Y!!!!2222222222!!dYd,YH?EJ?;HJ!'F?[JH9HC6?JH^HHA!!!22!,2,2,!222N2222%'22H22,,2,d! 22  222!!!! 222222 222 H,H,H,H,H,YCE,?,?,?,?,!!!!J2H2H2H2H2J2J2J2J2H2H,J2H2H2H2J292H,H,H,E,E,E,E,J2?,?,?,?,H2H2H2H2H2H2J2J2!!!!I8' F2?????J2J;J2J2H2H2YHC%C%C%6'6'6'6'???J2J2J2J2J2J2^HH2A,A,A,  J2?J2C%6'?H2H2J2H2J2!     22   !      !!/ddddddddddddddddddddddddddddddddddddddddddddddddNHHH2 22!,))22X222YY2#2222Y# !! 442Ydd22==Ld2d2H2 ;SS88Y    8!4      2  ^ x  #"ddddHHddd2Hdd4HHYYddd             2YYddd 
 Y2!!dddddH=dYHHHHHHHHHHx!d2H282YdHdC2!2H,29HNAddHHHHHHHHHHddddd.dHHHHddddddddddddd ddddddHHddddddSC=NdHd   dd    +;                                               HHHH                       dd          d        dd         dHHH2HHdHHddd   HH   H,   HHHH,   HHHHH   HHH   HHH   HHH   HHHHHHHHHHHHHH     H   HHHHHH    HHHHHHHH!   HHH!   HHH!   HHH!   HHHH   H                                                   H   HHHH   HHHH=?8  =8C,?'A,J2H,!F,C8[8J,C2H,H=92=2 2?,H,C=H8N===='2,,,=,= = == !!22222          22         ==================='''''''22222222222222222222,,,,,,,,,,,,,,,,,,,====================!  9  H?J!HH=2,! x "  m'^,,CTTe,,,T,,,,TTTTTTTTTT,,EcT^`MJc`%JYHy`eOhVVT```[Q,,,CC,HMHMH1MM  H tMMMM/C1MJtJJ@;C;,TT  TTT,,,, TTTTTT CTQ  cHcHcHcHcHr^HMHMHMHMH% % % % `MeMeMeMeM`M`M`M`M[JcH`MeMeM[J`MOMcHcHcH^H^H^H^H`MMHMHMHMHcMcMcMcMcMcM`M`M% % % % l@J YHH H H H0H `M`[`M`MeMeMyV/V/V/VCVCVCVCT1T1T1`M`M`M`M`M`Mt[JQ@Q@Q@  `MH `MV/VCT1[J[J`MeM`M,     CC   ,      ,,/N```C TT,EJJTTT66T44CCT4 ,, CCT11TTRReCC`C [{{QQ    K,C      C     4"``C`F``             C充  C,,`O``````````x,CcTJT`cC,T`CTM`hV``````````H```` ``oYQh`       9O                                               ````                                                  ```C````   ``   `;   ````;   `````   ```   ```   ```   ``````````````     `   ``````    ````````,   ```,   ```,   ```,   ````   `                                                   `   ````   ```cJTH  JCcHM>Q9`MeH% YCcEyJ`JT9eM`MOHOO ;T>[Hm^`@j[ceJ>M  MHHeHJ e [[ ,,TTTTT          TT         JJJJJJJJJJJJJJJJJJJ>>>>>>>MMMMMMMMMMMMMMMMMMMM            MMMMMMMHHHHHHHHHHHHeeeeeeeeeeeeeeeeeeee,  M  cM`%e[cC;,  "  m'^,,ETTe,,,T,,,,TTTTTTTTTT,,EcT^`MJc`%JYHy`eOhVVT```[Q,,,CC,HMHMH1MM  H tMMMM/C1MJtJJ@CCC,TT  TTT,,,, TTTTTT CTQ  cHcHcHcHcHr^HMHMHMHMH% % % % `MeMeMeMeM`M`M`M`M[JcH`MeMeM[J`MOMcHcHcH^H^H^H^H`MMHMHMHMHcMcMcMcMcMcM`M`M% % % % o@J YHH H H H4H%`M```M`MeMeMyV/V/V/VCVCVCVCT1T1T1`M`M`M`M`M`Mt[JQ@Q@Q@  `MH `MV/VCT1[J[J`MeM`M,     CC   ,      ,,/N```C TT,EJJTTT66T44CCT4 ,, CCT11TTRReCC`C [{{QQ    K,C      C     4"``C`J``             C充  C,,`Q``````````x,CcTOTmc@,T`JTM`h[``````````C```` ``tYQh`       9O                                               ````                                                  ```C````   ``   `C   ````C   `````   ```   ```   ```   ``````````````     `   ``````    ````````,   ```,   ```,   ```,   ````   `                                                   `   ````   ```cMTO  JCcMMCQ>`MeQ%#YCcCyO`J`@eMmQOMQV >T>[O{``J{`mhMCM##MOOhMV h [` ,,TTTTT          TT         MMMMMMMMMMMMMMMMMMMCCCCCCCMMMMMMMMMMMMMMMMMMMM############MMMMMMMOOOOOOOOOOOOhhhhhhhhhhhhhhhhhhhh,  Q  cM`%e[mC;,  ? x x x ,    wx 6X   @ 8; X@t T d d d ,   Wmd p   @ >pQ @Lt T d d d , '  wld p   @ ~rQ @u S d d d , @  d p,   ` Q t T d d d , ^  d p h QQ H H  < !  , ~ ,<     P 7,Pld ! T , , ,  QT x    P 7Pmd ! T , , ,  xT     p ?7> t T d d d ,   Vd p   @ h'  @nQq   ,  lFx    P 7FP^u &  ,  ~x&x    P 7xPZ[XPSQRWUft@ 2&  u bf
u~3b 
te!
 ! 5e!mo%:ںt!lbFu
l&l 2     	4	  2,  
4	  f5  	   R       >  "  D,(	0	^    V          M=E ME}  , EV^$$EEE4          l l  l             7              l   M M M M M =     } l } l } l } l EVVVVEEEE4 M EVV4 EM M M = = = = E    MMMMMMEE} l } l } l } l m    ,  l  l  l    l EE4EEVV$ $ $ $ $ $ $    EEEEEE4        E l E$ $  4 4 EVE                                   / N EEE                        V  E   4                                   " EE E EE                                    EEEEEEEEEEEx   M EM  E E^$EEEEEEEEEE EEEE  EEw,^E                                                                                                             EEEE                                                                                                     EEE EEEE      EE      E       EEEE       EEEEE      EEE      EEE      EEE      EEEEEEEEEEEEEE          E      EEEEEE        EEEEEEEE       EEE       EEE       EEE       EEEE      E                                                                                                      E      EEEE      EEE M        M   EV } l , M  E  VE     4 o=E f4MV  l l   V    V  44                                                                    l l l l l l l l l l l l             VVVVVVVVVVVVVVVVVVVV         ME} V4M      "  D,(	0	^    &&b   &    &&&&&&&&&&   Z&HQZQ 7 Qbk..&QQQ@          p p  p          9 &&    &&&      &&&&&&   &p   Z Z Z Z Z H      p  p  p  p QbbbbQQQQ@Z Qbb@QZ Z Z H H H H Q    ZZZZZZQQ p  p  p  p z   7  p  p  p    p QQ@QQbb. . . . . . . & & & QQQQQQ@       Q p Q. . & @@QbQ                                   / N QQQ   &&  &&&  &    &         &  &&b  Q   @                                  " QQ Q QQ                                    QQQQQQQQQQQx   Z&&QZ  &Q &Qk.QQQQQQQQQQ QQQQ  QQ7kQ                                                                                                             QQQQ                                                                                                     QQQ QQQQ      QQ      Q       QQQQ       QQQQQ      QQQ      QQQ      QQQ      QQQQQQQQQQQQQQ          Q      QQQQQQ        QQQQQQQQ       QQQ       QQQ       QQQ       QQQQ      Q                                                                                                      Q      QQQQ      QQQ Z&      Z   Qb  p 7 Z Q& bQ    & @ |HQ t@Zb p p   b   b  @@    &&&&&                    &&                         p p p p p p p p p p p p             bbbbbbbbbbbbbbbbbbbb         ZQ b@Z       	   (#.   4              U UUUUUUUUUUUU      Y 5     D 9$%  #  }| 2    PkC LlP#     User-Specified Data
u            P        $User-Specified DataX 4     C z?#e
$  #  }| 2    PkC LlP#     Models and Formats
u            P        #Models and Formats &   
]f]f 
 
]  
  
2w2
  
U
   2
   2
  J J2Q -     < t   #  }| 2    PkC LlP#     TRANSLATORS
u            P        hTRANSLATORSG #     2 ]  #  }| 2    PkC LlP#     A
u            P        AG #     2 u  #  }| 2    PkC LlP#     B
u            P        BG #     2   #  }| 2    PkC LlP#     C
u            P        CG #     2   #  }| 2    PkC LlP#     D
u            P         DR .     = l  #  }| 2    PkC LlP#     SDTS PROFILE
u            P        -SDTS PROFILEc ?     N K  #  }| 2    PkC LlP#     FIPS PUB 123 FUNCTION LIBRARY
u            P      #  {FIPS PUB 123 FUNCTION LIBRARY & 	M     h  
  /lA
  /_A	`eh     h  
  pW 9     B `
  #  }| 2    PkC LlP#     SDTS FIPS PUB123  & 
u            P        
SDTS FIPS PUB123 T 6     ? `
j  #  }| 2    PkC LlP#     Transfer Files & 
u            P        
^Transfer Files	Q&     h  
  3&E#
  3&E#	i#h     h  G )     2 #%  #  }| 2    PkC LlP#     C & 
u            P        $C
  # 	lR&     h  
  q4&F#
  d4&F#	j#h     h  G )     2 $%  #  }| 2    PkC LlP#     A & 
u            P        $A
  # 	R&     h  
  4&F#
  ~4&F#	j#h     h  G )     2 #%  #  }| 2    PkC LlP#     B & 
u            P        $B
  # 	R&     h  
  
4&tF#
  4&gF#	hj#h     h  G )     2 #d%  #  }| 2    PkC LlP#     D & 
u            P        k$D
  }#}    t T    #  d p   @ >pQ Wm@#  }        X     +# d p   @ >pQ Wm@# Programmers Reference Manual for FIPS PUB 123 Function Library

}                   ߉  t T    3/93 `	`	  " hh( . 3 pp9 ?   E xxK   P                     X`	hp x (#%'0*,.8135@8:<H?A                      X`	hp x (#%'0*,.8135@8:<H?A                     1.`	`	 GENERAL INFORMATION

  t T X 1.1`	`	 SUMMARY

 `	`	 The FIPS PUB 123 Function Library software provides access to files
in the FIPS PUB 123 (ISO 8211) data descriptive file format.  The
library functions are callable routines for use by other application
programs.  These functions encode userspecified data models and
formats into the FIPS 123 format and decode data from the FIPS 123
format to userspecified data models.  As shown in figure 1, the
FIPS PUB 123 Function Library forms the foundation of the conversion
model for the Spatial Data Transfer Standard (SDTS, FIPS PUB 173).(#`	

  t T < 1.2`	`	 ENVIRONMENT

 `	`	 The FIPS PUB 123 Function Library is currently supported in three
operating environments:  the IBMcompatible personal computer (PC)
under MSDOS, the Data General (DG) Aviion under DG/UX, and the
Amdahl 5890 mainframe under MVS/ESA.  The software is written in C
and is compliant with the American National Standards Institute
(ANSI) specification on C language.  Therefore, it is easily
portable to other vendor hardware, operating systems, and compilers. 
The functions are Ccallable routines and may be recompiled to
create routines that may be used by applications written in other
languages.(#`	

 `	`	 The following paragraphs describe the environments in which the
Function Library is currently supported.  Additional paragraphs will
be added as the software is "ported" to other environments.(#`	
   !         0*%%    !  Ln!                   (#.  d d     SDTS.GEM                                             L%*   JZs~ #  d p   @ ~rQ wl@# 

  Figure 1
 Conversion Model for the Spatial Data Transfer Standard.
  $  (#(#  (#(#  ! '#$  0             0*%% '#O-  !  0    t T    1.2.1`	`	 Personal Computer

 `	`	 The FIPS PUB 123 Function Library has been implemented 

on the
following personal computers (PCs) using the MSDOS operating
system: IBM 386, IBM AT, and IBM XT (or compatibles).  The specific
software and hardware requirements for the FIPS PUB 123 Function
Library in the PC environment are described below.(#`	

  t T `	 1.2.1.1 `	`	 Software(#`	

 `	`	 The PC version of the FIPS PUB 123 Function Library is supported
under Microsoft DOS (MSDOS), versions 3.2 and later.  The software
was compiled using the Microsoft C compiler, version 5.1.    (#`	

  t T h 1.2.1.2 `	`	 Hardware(#`	

 `	`	 The FIPS PUB 123 Function Library source code requires approximately
1.2MB of disk space; the object code compiled using Microsoft C
requires approximately 200KB of disk space.  The source and object
code of the sample programs require an additional 105KB of disk
space.  Object code space requirements will vary depending on
compiler options specified.(#`	

 `	`	 The memory required to execute applications developed using the FIPS
PUB 123 Function Library will vary depending on the size of the
application, the number of functions called, the size of the input
and output records, and the use of a source code debugger.  MSDOS
restricts the amount of base memory available to execute all
programs to 640K.  Some of this base memory is used by the MSDOS
operating system itself and by terminate and stay resident (TSR)
programs such as disk, display, input, and network device drivers. 
It is desirable to have as much base memory available to the FIPS   T$        0*%%  PUB 123 application as possible.  Therefore large applications, or
applications processing large data files, may require that all nonessential TSRs be removed from memory.  Data files containing large
records may be processed more efficiently by field or subfield than
by whole record.  (#`	

 `	`	 In order to preserve code portability, extended or expanded memory
is not used by the FIPS PUB 123 Function Library; however, the
Microsoft C 5.1 CodeView Debugger uses extended memory to store a
symbol table.  (#`	

 `	`	 The FIPS PUB 123 Function Library restricts its I/O to disk files;
therefore, no specific display adapter is required.  The sample
programs included with the FIPS PUB 123 Function Library output text
to the screen but also do not require display adapters with graphics
capabilities. (#`	

  t T  1.2.2 `	`	 Data General(#`	

 `	`	 The FIPS PUB 123 Function Library is also supported on the Data
General (DG) Aviion workstation or server under the DG/UX operating
system.  The specific software and hardware requirements for the
FIPS PUB 123 Function Library in the DG environment are described
below.(#`	

  t T L 1.2.2.1 `	`	 Software(#`	

 `	`	 The DG version of the FIPS PUB 123 Function Library was compiled
with the GNU C compiler, version 3.2.1.3, under the DG/UX operating
system, release 5.4.1, which corresponds to AT&T UNIX System V,
Release 5.4.1.(#`	
   T$         0*%%  Ԍ  t T    1.2.2.2 `	`	 Hardware(#`	

 `	`	 The FIPS PUB 123 Function Library has been implemented on a DG
Aviion (model AV300) which is based on a Motorola 88100 MHz
uniprocessor and configured with a minimum of 8MB of main memory. 
The source code requires approximately 1.2MB of disk space; object
code compiled using the GNU C compiler requires approximately 180KB
  t T 4 of disk space.  The source and object code of the sample programs
require an additional 125KB of disk space.  Object code space
requirements will vary depending on the compiler options specified.(#`	

 `	`	 The memory required to execute applications developed using the FIPS
PUB 123 Function Library will vary depending on the size of the
application, the number of functions called, the size of the input
and output records, and the use of a source code debugger.  DG/UX
uses disk swapping to execute programs.  There are no memory
restrictions on program execution as long as sufficient swap space
exists. (#`	
 `	`	 (#`	            0*%%    t T    1.3`	`	 REFERENCES

  t T X `	`	   o X" American National Standard for Information Systems 
  t T  Programming Language  C, ANSI X3.1591989(#

  t T  `	`	   o X" American National Standard Specification for a Data
  t T  Descriptive File for Information Interchange, FIPS PUB
123, February 28, 1986 (ANSI/ISO 82111985)(#

  t T 
  `	`	  X o X" DG/UX Manual Pages for GNU C (gcc) and Archive and
Library Maintainer (ar)(#

  t T   `	`	  X o X" IBM C/370, Programming Guide, Version 2, Release 1.0,
  t T < International Business Machine Corp., March 1991(#(#V (#

  t T   `	`	  X o X" Microsoft C 5.1 Optimizing Compiler (Language  P Reference, Users Guide, Run Time Reference, Mixed
Language Programming Guide)(#

  t T D  `	`	  X o X" Spatial Data Transfer Standard, FIPS PUB 173, August 28,
  t T p 1992hh( (#

  t T   `	`	  X o X" UNIX System V Release 3, 1986, 4 vol.xxK   P (#

  t T    `	`	  X o X" Using TCP/IP on the DG/UX System, Data General
Corporation, May 1990, [09370102302](#

  t T   `	`	  X o X" Using the DG/UX System, Data General Corporation, Feb.
1990, [06970103501](#

  t T (# `	`	   o X" Using the DG/UX Editors, Data General Corporation, Feb.
1990, 243 p.(#   T$        0*%%  Ԍ  t T    ԙ1.4`	`	 DOCUMENT ORGANIZATION

 `	`	 The format and content of this document are in compliance with the
  t T  NMD Standards for Preparation of Technical Instructions, Part 9,
  t T  Programmers Reference Manuals (Draft 12/22/92).  Section 1 provides
general information about the document and the operating environment
required by the FIPS PUB 123 Function Library.  Section 2 provides
instructions for installing the software and building a function
library in each operating environment.  Section 3 provides general
guidelines for the use of the FIPS PUB 123 Function Library and
describes each of the library functions.  Section 4 provides a point
of contact for the software and describes the change control
procedures.(#`	

 `	`	 The document also includes five appendices which are organized as
follows:(#`	

  t T   `	`	  X o X" Appendix Aprovides a glossary of data elements, terms,
and acronyms referenced within this document(#

  t T p  `	`	  X o X" Appendix Bprovides an overview of the FIPS PUB 123(#

  t T   `	`	  X o X" Appendix Cprovides a description of each INCLUDE file
used by the FIPS PUB 123 Function Library(#

  t T L  `	`	  X o X" Appendix Ddescribes error handling within the FIPS PUB
123 Function Library(#

  t T    `	`	  X o X" Appendix Edescribes sample programs that may be used
to test the functions, including installation and
operating instructions, and a listing of the source code(#
   T$         0*%%  Ԍ  t T     `	`	  X o X" Appendix Fdescribes the ASCII/EBCDIC conversion
program that may be used to convert data files between
the ASCII and EBCDIC character sets for different
operating environments (To be provided at a later date).(#           0*%%    t T    2.`	`	 INSTALLATION PROCEDURES

 `	`	 This section describes the procedures required to install the FIPS
PUB 123 Function Library, create a new function library, create an
executable application, and transfer the library between platforms. 
The FIPS PUB 123 Function Library is currently distributed in two
formats:(#`	

  t T `	  `	`	  X o X" MSDOS disketteincludes the FIPS PUB 123 source code
and function library compiled under Microsoft C, version
5.1(#

  u T   `	`	  X o X" UNIX tar diskette or magnetic tape cartridgeincludes
the FIPS PUB 123 source code and function library
compiled on the Data General (DG/UX) under the GNU C
compiler, version 3.2.1.3(#

  t T   `	`	  X o X" MVS IBM standard labeled tape/ANSI standard labeled
  t T  tape.1(#

 `	`	 The installation procedures described herein are specific to the
compilers and linkers currently supported.  The commands and options
used to compile, link, and create a library may differ for other
compilers.(#`	




  t T   `	`	 1  Includes the FIPS PUB 123 Function Library source code and the
function library compiled under IBM C/370, Version 2, Release
1.0.(#
   U$	         0*%%  Ԍ  t T    ԙ2.1 `	`	 PERSONAL COMPUTER(#`	

  t T X 2.1.1 `	`	 Installing the FIPS PUB 123 Function Library(#`	

 `	`	 The MSDOS version of the FIPS PUB 123 Function Library and support
software are provided on 1.44/1.2MB floppy diskettes.  These
diskettes contain the source and object code, documentation, 'make'
files for compiling and library building using Microsoft C 5.1, and
sample programs in a selfextracting compressed format.  To install(#`	

 `	`	 the software, insert the FIPS PUB 123 Function Library diskette into
the appropriate drive and enter: (#`	

  u T <  `	`	  X <drive>:install(#
 `	`	 or(#`	
  u T   `	`	  X <drive>:load123 <f123dir>(#

  t T   `	`	 where <drive> contains the FIPS PUB 123 diskette, and <f123dir> is
the root directory into which the software is to be installed.  The
  u T F install program is an aid to invoking the load123 program.  Install
will prompt for and create the directory structure into which the
  u T  software is to be installed before invoking the load123 program. 
  u T  The load123 program may be invoked to extract and copy the software
into the following subdirectories within the current directory or
  t T % the directory specified by <f123dir>:(#`	

  t T }  `	`	 Directory "  Xhh(  X. Description(#
  u T   `	`	 \<f123dir>\f123app `	. FIPS PUB 123 sample application programs (#
  u T    `	`	 \<f123dir>\f123bat `	. FIPS PUB 123 .bat files to create the
Function Library(#
  u T /#  `	`	 \<f123dir>\f123doc `	. Introductory documentation (readme.123) and
FIPS PUB 123 Programmers Reference Manual(#   \$
        0*%%  Ԍ  u T     `	`	 \<f123dir>\f123inc `	. Include (.h) files used by FIPS PUB 123
functions(#
  u T Y  `	`	 \<f123dir>\f123lib `	. FIPS PUB 123 Function Library (#
  u T   `	`	 \<f123dir>\f123lst `	. Compiled source code listings for FIPS PUB
123 functions(#
  u T   `	`	 \<f123dir>\f123obj `	. Object code for FIPS PUB 123 functions(#
  u T   `	`	 \<f123dir>\f123src `	. Source code for FIPS PUB 123 functions(#
  u T 9  `	`	 \<f123dir>\f123utl `	. FIPS PUB 123 utility programs(#
  u T f	  `	`	 \<f123dir>\samdlg3 `	. U.S. Geological Survey Digital Line Graph
Level 3 data files in SDTS format (DLG3/SDTS)(#
  u T   `	`	 \<f123dir>\samtiger `	. U.S. Bureau of the Census Topologically
Integrated Geographic Encoding and
Referencing (TIGER) data files in SDTS
format (TIGER/SDTS).(#

 `	`	 After successful extraction, copy the new library to the appropriate
subdirectory where other C libraries are located.  The FIPS PUB 123
Function Library may now be used to create an application compiled
under Microsoft C (See paragraph 2.1.3).(#`	

 `	`	 If another compiler is to be used, the FIPS PUB 123 Function Library
must be rebuilt.  The procedures discussed in paragraph 2.1.2 and
the command files provided may be modified to reflect the
procedures/options of the new compiler.(#`	

  t T  2.1.2 `	`	 Creating the FIPS PUB 123 Function Library(#`	

  u T    `	`	 Prior to compiling, edit the include file stc123.h to ensure that
  u T " the constant MSDOS is defined as 1 (one) and all other operating
  t T 2# system compilation constants are defined as 0 (zero) (see figure 2). 
  u T ^$ Use the f123comp.bat file to compile each routine in   ^$        0*%%    u T    \<f123dir>\f123src\ and generate the object code in directory
  u T - \<f123dir>\f123obj\.  The following compile options are used to
compile the source code using Microsoft C version 5.1:(#`	

  u T  `	`	   cl /Os /AL /c /Fs..\f123lst\ /W3 /I..\f123inc\ /Fo..\f123obj\
  u T    (#(#(#(#   `	`	    X" ..\f123src\<source>.c(#

 A  x    K              d d Zs                                                       x* Zs 
  t T   #  d p   @ >pQ Wm@# H
  Figure 2
  u T  x The stc123.h File Specifies the MSDOS Platform.#  d p   @ >pQ Wm@# 
 /*************************************************************************
 *  The following constants are defined to control compilation in         *
 *  several operating environments.  Only the constant referring to your  *
 *  operating system should be set to '1' (one) all others should be      *
 *  set to '0' (zero).                                                    *
 *************************************************************************/

  #define MSDOS 1    /* Microsoft DOS */Ɛ
  #define DG 0       /* Data General DG/UX */Ɛ
 #define MVS 0      /* Amdahl MVS */ 

 /************************************************************************/


 
$  (#(#d	(#(#0A '#$ 

`	`	 where:

  t T D `	`	   o X" /Osĩoptimizes for size reduction(#

  t T !  `	`	  X o X" /ALĩuses the large memory model(#

  t T #  `	`	  X o X" /cĩperforms a compile and produces object code(# 0  #         0*%% '#!A  0  Ԍ  t T    ԙ `	`	  X o X" /Fsĩproduces a source listing file placed in
  u T , \<f123dir>\f123lst\(#

  t T  `	`	   o X" /W3ĩdisplays level 3 warnings(#

  t T  `	`	   o X" /Iĩspecifies that compile should also search directory
  u T 	 \<f123dir>\f123inc\ for include files(#

  u T b	 `	`	   o X" /Foĩspecifies that the object files (*.obj) are to be
  u T 
 placed in directory \<f123dir>\f123obj\(#

  u T  `	`	   o X" <source>.cĩC source code file located in directory
  u T  \<f123dir>\f123src\.(#

 `	`	 If the Microsoft CodeView debugger is to be used, replace option 
  t T  /Os with the options /Zi and /Od.  The /Zi option creates object
  t T  code for use with CodeView and the /Od option disables code
  u T  optimization.  Note: the object code produced with these options
will be larger.(#`	

 `	`	 Create a run-time library after obtaining the object code for each
  u T  routine.  Microsoft C provides the library manager LIB to create,
organize, and maintain run-time libraries.  A response file
  u T  f123lib.rsp is included for input to the library manager to generate
the library (see figure 3).  (#`	
 Aa  hx     K          z  h  d d Zs                                                      xh* Zs    ?     #  d p   @ >pQ Wm@# 
H
  Figure 3
  u T   FIPS PUB 123 MSDOS Library Response File (f123lib.rsp).#  d p   @ >pQ Wm@# 
  ..\f123lib\fips123Ɛ
  yƐ
  + a_toe + bak_fld + bak_rec + bak_sfld + beg_ddre + beg_file&Ɛ
  + beg_rec + bld_fmt + bld_lab + chk_fld + chk_nfld&Ɛ
  + chk_nrec + chk_nsfl + chk_rec + chk_sfld + ch_size&Ɛ
  + cki_nfld + c_dddir + c_ddlead + c_drdir + c_drlead&Ɛ
  + conv_cat + deldrval + del_dim + del_fmt + del_labs + e_toa&Ɛ
 + end_ddre + end_file + end_rec + er_ddfld + er_ddrec + er_ddsfl&
  + free_lab + gdstr + get_dim + get_dval + get_fmt&Ɛ
  + get_lvl + gbstr + gfstr + gint + g_order + gstr + gsstr&Ɛ
 + incr_lab + is_intgr + i_toa + ld_ddrec + ld_rec + load_fld&
  + ld_tagp + load_fmt + load_lab + l_tos + out_fmt + pop_rs&Ɛ
  + push_rs + r_dddir + r_ddlead + r_drdir + r_drlead&Ɛ
 + rd_ddfld + rd_ddrec + rd_ddsfl + rd_fld + rd_rec + rd_sfld&
  t T   + ret_dv + ret_fv + ret_matc  hhh( + ret_pdm + rt_pvfld + rt_pvsfl&Ɛh
 + setup_lb + set_stat + stc_empt + s_tol + stor_dv&
 + str_tok + uld_ddre + uld_rec + v_ddtag + v_drtag + wint&
 + wr_ddfld + wr_ddrec + wr_ddsfl + wr_fld + wr_rec + wr_sfld&
  ..\f123lib\fips123.xrfƐ
A 
 `	`	 The response file contains:(#`	

  t T    `	`	  X o X" Line 1the name of the library(#


 0  ]$
         0*%% '#  a  0  Ԍ$  (#(#  (#(#Pa '#$ ԙ
  t T |  `	`	  X o X" Line 2the character "y" indicating the named library
is to be created if it does not exist(#

  t T    `	`	  X o X" Lines 3 through nthe list of files (excluding
extension) to be included in the library.  The "+"
character precedes each filename; the "&" character at
the end of a line indicates continued filenames(#

  t T   `	`	  X o X" Line n+1the name of the cross-reference listing to be
created.(#
  


 0  $         0*%% '#  a  0  Ԍ `	`	 Invoke the Microsoft C library manager by using the command(#`	

  u T X `	`	  lib @f123lib.rsp
 `	`	 (#`	
  u T   `	`	 The response file f123lib.rsp creates the library fips123.lib and
  u T  generates the cross-reference listing file fips123.xrf.  Move the
new library to the appropriate subdirectory where other C libraries
are located.  The FIPS PUB 123 Function Library may now be used to
create an application compiled under Microsoft C (see paragraph
2.1.3).(#`	

 `	`	 If another compiler is used, the procedures discussed in this
paragraph and the command files provided may be modified to reflect
the procedures/options of the new compiler.(#`	

  t T  2.1.3 `	`	 Creating an Executable Application (#`	

   `	`	 Prior to compiling the application program(s), 'include' the FIPS
  u T  PUB 123 Function Library header file stc123.h in the main
application program and in each subroutine that calls a FIPS PUB 123
function.  To link an application program with the FIPS PUB 123
Function Library using the Microsoft C Linker, use the command(#`	

  u T  `	`	  link /co <app_pgm>

 `	`	 where:(#`	

  t T  `	`	  o `	" /coĩprepares the executable for debugging.  This option
  t T   may be used only if the /Zi and /Od options were used
when the application program was compiled(#

   Y$         0*%%  Ԍ  t T     `	`	  X o X" <app_pgm>identifies the main application program
object file. (#

 `	`	 The linker prompts for the names of the executable file, the list
file, and the library.  At the library prompt, enter the name of the
FIPS PUB 123 Function Library created using the library manager,
either:(#`	

  u T `	  `	`	  X \<f123dir>\f123lib\fips123.lib(#

 `	`	 or another library to which the FIPS PUB 123 Function Library was
copied.(#`	

  t T =  `	`	 Consult the Microsoft C Optimizing Compiler documentation if errors
are encountered during the link step.  Upon successful linking, your
FIPS PUB 123 Function Library application is ready to execute. (#`	

  t T  2.2`	`	 UNIX

  t T E 2.2.1 `	`	 Installing the FIPS PUB 123 Function Library(#`	

 `	`	 The UNIX version of the FIPS PUB 123 Function Library and support
software are available on 



diskette or magnetic tape cassette and
  u T  cartridge.  The media was created using the UNIX tar command and
contains the source and object code, documentation, 'make' files for
compiling and library building using the GNU C compiler (v.
3.2.1.3), and sample programs.  To install the software, load the
media into the appropriate device and enter:(#`	

  u T !  `	`	  X cd <f123dir>(#
  u T +#  `	`	  X tar xv<#>; install(#
   X$         0*%%  Ԍ `	`	 where:(#`	

  t T X `	`	  o `	" <f123dir> specifies the root directory into which the
software is to be installed(#

  u T   `	`	  X o X" éxv are the tar arguments for file extraction and
verbose(#

  t T a	  `	`	  X o X" <#> is a digit 09 corresponding to the diskette or tape
cassette/cartridge device.  For example, if the device
  t T  is /dev/rmt/0, then <#> is 0.  (#


  u T =  `	`	 The UNIX tape archival utility (tar) copies the software into the
following directories:(#`	

  t T  `	`	   Directory hh(  X.  X3 Description(#

  u T   `	`	  <f123dir>/f123app `	.  X3 FIPS PUB 123 sample application
programs (#
  u T s `	`	   <f123dir>/f123bat .  X3 FIPS PUB 123 .bat files to create the
FIPS PUB 123 Function Library(#
  u T  `	`	   <f123dir>/f123doc .  X3 Introductory documentation
  u T  (readme.123) and the Programmers
Reference Manual for FIPS PUB 123
Function Library (#
  u T ~ `	`	   <f123dir>/f123inc .  X3 Include (.h) files used by FIPS PUB
123 functions(#
  u T   `	`	   <f123dir>/f123lib .  X3 FIPS PUB 123 Function Library (#
  u T " `	`	   <f123dir>/f123lst .  X3 Compiled source code listings for
FIPS PUB 123 functions(#
   ]$         0*%%  Ԍ  u T    `	`	   <f123dir>/f123obj .  X3 Object code for FIPS PUB 123
functions(#
  u T Y `	`	   <f123dir>/f123src .  X3 Source code for FIPS PUB 123
functions(#
  u T  `	`	   <f123dir>/f123utl .  X3 FIPS PUB 123 Function Library utility
programs(#
  u T  `	`	   <f123dir>/samdlg3 .  X3 U.S. Geological Survey Digital Line
Graph level 3 data files in SDTS
format (DLG3/SDTS)(#
  u T 
 `	`	   <f123dir>/samtiger `	3 U.S. Bureau of the Census
Topologically Integrated Geographic
Encoding and Referencing data files
in SDTS format (TIGER/SDTS) (#

 `	`	 After successful loading, copy the new library to the appropriate
subdirectory where other C libraries are located.  The FIPS PUB 123
Function Library may be used to create an application compiled under
the GNU C compiler (see paragraph 2.2.3).(#`	

 `	`	 If another compiler is to be used, the FIPS PUB 123 Function Library
may require rebuilding.  Follow the procedures discussed in
paragraph 2.2.2 modified to reflect the procedures/options of the
new compiler.(#`	

  t T % 2.2.2 `	`	 Creating the FIPS PUB 123 Function Library(#`	

  u T }  `	`	 Prior to compiling, edit the include file stc123.h to ensure that
  t T  the appropriate UNIX constant is defined as 1 (one) and that all
other operating system compilation constants are set to 0 (zero). 
  u T " (This constant is currently defined only for the Data General (DG)
  u T /# UNIX platform as shown in figure 4.)  Use the f123comp.m 'make' file
  u T \$ to compile each routine in <f123dir>/f123src/ and generate the   \$        0*%%    u T    object code in directory <f123dir>/f123obj/.  The following compile
options are used to compile the source code using the GNU C Compiler
(v. 3.2.1.3):(#`	

  u T   `	`	  X gcc éc éWall éansi épedantic éI../f123inc
  u T  ../f123src/<source>.c(#
   x    K              d d Zs                                                       x* Zs 
  t T   #  d p   @ >pQ Wm@# H
  Figure 4
  u T  
 The stc123.h File Specifies the UNIX Platform.#  d p   @ >pQ Wm@# 
 /*************************************************************************
 *  The following constants are defined to control compilation in         *
 *  several operating environments.  Only the constant referring to your  *
 *  operating system should be set to '1' (one) all others should be      *
 *  set to '0' (zero).                                                    *
 *************************************************************************/

  #define MSDOS 0    /* Microsoft DOS */Ɛ
  #define DG 1       /* Data General DG/UX */Ɛ
 #define MVS 0      /* Amdahl MVS */

 /************************************************************************/


 
$  (#(#7(#(#0 '#$ 
  t T   `	`	 where X :(#

  t T  `	`	  o `	" écĩperforms a compile and produces object code(#

  t T C  `	`	  X o X" éWallĩprints extra warning messages(#

  t T !  `	`	  X o X" éansiĩsupports all ANSI standard C features; turns off
certain features of GNU C that are incompatible with
ANSI C(# 0  #        0*%% '#   0  Ԍ  t T    ԙ `	`	  X o X" épedanticĩissues all warnings demanded by strict ANSI
standard C(#

  t T   `	`	  X o X" éIĩspecifies the compiler should also search 
  u T  <f123dir>/f123inc for include files.(#

  u T 	  `	`	 If the standard UNIX source code debugger sdb is to be used, the ég
compile option must be used in addition to the above options.  Note
  t T b	 that the object code produced with the ég option will be larger.(#`	

 `	`	 Create a run-time library after obtaining the object code for each
  u T  routine.  UNIX provides the archive and library maintainer ar to
create and update library files to be used by the link editor.  The
  u T ? shell script f123lib.m is included to generate the library.  The
shell script contains the command: (#`	

  u T   `	`	  X ar éruv ../f123lib/fips123.a ../f123obj/*.o(#

 `	`	 where:(#`	

  t T u  `	`	  X o X" rĩreplaces files in archive(#

  t T   `	`	  X o X" uĩadds only new or updated files(#

  t T %  `	`	  X o X" vĩprovides a verbose listing of archive actions(#

  u T }  `	`	  X o X" ../f123lib/fips123.aĩspecifies the library name(#

  u T    `	`	  X o X" ../f123obj/*.oĩindicates a wildcard file specification
  u T " representing a list of files with  '.o' extensions that
are to be included in the library.(#
   \$         0*%%  Ԍ  u T     `	`	 Invoke f123lib.m as a standard UNIX shell script to build the
  u T - library.  This shell script creates the library named fips123.a.  
The FIPS PUB 123 Function Library may now be used to create an
application compiled under the GNU C Compiler (see paragraph 2.2.3).(#`	

 `	`	 If another compiler is used, the procedures discussed in this
paragraph and the makefile provided may be modified to reflect the
procedures and options of the new compiler.(#`	

  t T 
 2.2.3 `	`	 Creating an Executable Application (#`	

   `	`	 Prior to compiling the application program(s), 'include' the FIPS
  u T  PUB 123 Function Library header file stc123.h in the main
application program and in each subroutine that calls a FIPS PUB 123
function.  To link an application program with the FIPS PUB 123
  u T  Function Library modify one of the sample makefiles sam_prg2.mak, 
  u T  samprg2b.mak, sam_prg3.mak, or samprg3b.mak (see figure 5) to
reflect the correct: (#`	
   !Vx     K              <6  d d                                                       `	*  #  d p   @ >pQ Wm@# 
H
  Figure 5
  u T   Sample Link Makefile (sam_prg2.mak).   #  d p   @ >pQ Wm@# 
  u T     CC = gcc ég -Wall -ansi -pedantic -I../f123incƐ

  u T Y   PGMNAME= ../f123app/sam_prg2Ɛ

  u T    SOURCE= ../f123app/sam_prg2.cƐ

  u T {   OBJECTS= ../f123obj/sam_prg2.oƐ

  u T    LIB= ../f123lib/fips123.aƐ

  all: setup $(PGMNAME)Ɛ

  setup:Ɛ

  $(OBJECTS): $(SOURCE)Ɛ
  u T     X cd ../f123obj; $(CC)  -c $(SOURCE)Ɛ

  $(PGMNAME): $(OBJECTS)Ɛ
  t T     X $(CC) $(OBJECTS) $(LIB) -o $(PGMNAME)Ɛ
 
 
  t T I  `	`	  X o X" Options to compile the application program(#
  t T u  `	`	  X o X" Program name(#
  t T   `	`	  X o X" Name of the object module(#
  t T   `	`	  X o X" Name of the library with which to link.(#

  u T %  `	`	 Invoke the make utility to create the executable using the following
command:(#`	
`	`	 
  u T  `	`	  make éf <app_pgm>.mak



 0  [$         0*%% '#p    0  Ԍ$  (#(#  (#(# '#$ ԙ
  t T D  `	`	 where X :(#

  u T  `	`	  o `	" éf indicates that the file <app_pgm>.mak  contains the
  u T  instructions for the make command(#

  u T "  `	`	  X o X" <app_pgm>.mak is the name of the sample application
makefile.(#

 `	`	 It is recommended that only two libraries be used when linking:  the
library containing the application object code and the FIPS PUB 123
Function Library.  The application library should be listed first
followed by the FIPS PUB 123 Function Library.  The UNIX linker/
loader will access the application library first and attempt to 0  W$        0*%% '#p    0  resolve all unresolved references in the FIPS PUB 123 Function
Library.  The linker/loader will not return to previously accessed
libraries.  Consult the UNIX Manual Pages if errors are encountered
during the link step.  Upon successful linking, your FIPS PUB 123 
application is ready to execute. (#`	

  t T  2.3 `	`	 MVS(#`	

`	`	 To be provided at a later date.

  t T  2.4 `	`	 TRANSFERRING THE FIPS PUB 123 FUNCTION LIBRARY(#`	
        
 `	`	 Use the File Transfer Protocol (FTP) command to transfer the FIPS
PUB 123 Function Library from one physical platform to another.  The
source code may be moved to any platform; however, the library will
only be functional if moved to an identical environment, that is,
  u T  having the same hardware and compiler.  The library file (fips123.a
  u T  or fips123.lib) and all FIPS PUB 123 data files (*.ddf) must be
  u T  transferred as type binary; all other files may be transferred as
  u T G type ascii.  Consult Using TCP/IP on the DG/UX System or your site
network administrator for additional information concerning FTP.(#`	
            0*%%    t T    3.`	`	 SOFTWARE FUNCTIONS

  t T X 3.1`	`	 OVERVIEW

 `	`	 This section provides a description of the usage of the FIPS PUB 123
functions.  The software FIPS PUB 123 Function Library provides the
tools to process the Data Descriptive Record (DDR) and Data Records
(DRs) within a FIPS PUB 123 Data Descriptive File (DDF).  The
functions allow the user to read, write, and erase these records by
record, field, or subfield levels of access.  (#`	

 `	`	 Definitions of terms within this document, including the function
parameters identified in boldprint in paragraph 3.3, are provided in
appendix A; appendix B provides an overview of the structure of a
FIPS PUB 123 DDF.  For a detailed explanation of the terms,
variables, and structure of the FIPS PUB 123 format, please refer to
the standard. (#`	

 `	`	 Table 1 identifies the file and data manipulation functions
contained in the FIPS PUB 123 Function Library.  To assist the
application programmer, figure 6 depicts a typical sequence for
calling these functions when writing a FIPS PUB 123 file.  In this
figure, node data are decoded from a userspecified data model and
formatted into the FIPS PUB 123 format.  An asterisk identifies an
optional step.  Figure 7 depicts a typical sequence for reading a
FIPS PUB 123 file.  (#`	   L        0*%%     . Table 1

! File/Data Manipulation Functions


`	`	                                                               

 `	`	  X Function            Purpose(#
`	`	                                                               

  t T   `	`	      bak123fld()hh(  . Backs up to the beginning of the last DR
field read or written(#
 `	`	  
  t T `	 `	`	  bak123rec()hh(  . Backs up to the beginning of the last DR
read or written(#
 `	`	 
  t T  `	`	  bak123sfld() . Backs up to the beginning of the last DR
subfield read or written(#

  t T  `	`	  beg123ddrec() . Initializes a DDR for the input or output
file(#

  t T h `	`	  beg123file() . Opens an input or output file for
processing(#

  t T  `	`	  beg123rec()hh(  . Initializes a DR for the input or output
file(#

  t T  `	`	  chk123fld()hh(  . Retrieves a description of the last DR
field read or written(#

  t T p `	`	  chk123nfld() . Retrieves a description of the next DR
field to be read or the last one written(#

  t T  `	`	  chk123nrec() . Retrieves a description of the next DR to
be read or the last one written(#

  t T   `	`	  chk123nsfld() . Retrieves a description of the next DR
subfield to be read or written(#
 `	`	 
  t T x `	`	  chk123rec()hh(  . Retrieves a description of the last DR read
or written(#

`	`	                                                                            0*%%  h( Table 1Continued

! File/Data Manipulation Functions


`	`	                                                               

 `	`	  X Function             Purpose(#
`	`	                                                               

  t T  `	`	  chk123sfld() . Retrieves a description of the last DR
subfield read or written(#

  t T `	 `	`	  end123ddrec() . Terminates DDR processing(#

  t T 
 `	`	  end123file(). Closes an input or output file

  t T  `	`	  end123rec()hh(  . Terminates the processing of a DR(#

  t T  `	`	  er123ddfld(). Erases the last DDR field written

  t T  `	`	  er123ddrec() . Erases the entire DDR written(#

  t T 0 `	`	  er123ddsfld(). Erases the last DDR subfield written

  t T   `	`	  X g123order() hh(  X. Returns the byte order of the current
machine (big, little, or middle endian)(#

  t T   `	`	  X l123tos() hh(  X. Converts a long integer to a character
string(#

  t T p `	`	  rd123ddfld(). Reads the next DDR field

  t T   `	`	  rd123ddrec(). Reads the entire DDR 

  t T  `	`	  rd123ddsfld(). Reads the next DDR subfield

  t T   `	`	  rd123fld()hh(  . Reads the next DR field(#

  t T  `	`	  rd123rec()hh(  . Reads the next DR(#

  t T @ `	`	  rd123sfld()hh(  . Reads the next DR subfield(#

  t T    `	`	  X s123tol() hh(  X. Converts a character string to a long
integer(#

`	`	                                                                  (#         0*%%  h( Table 1Continued

! File/Data Manipulation Functions


`	`	                                                               

 `	`	  X Function             Purpose(#
`	`	                                                               

  t T  `	`	  wr123ddfld(). Writes a DDR field

  t T  `	`	  wr123ddrec(). Writes the DDR 

  t T (
 `	`	  wr123ddsfld(). Writes a DDR subfield

  t T  `	`	  wr123fld()hh(  . Writes a DR field(#

  t T H
 `	`	  wr123rec()hh(  . Writes a complete DR(#

  t T  `	`	  wr123sfld()hh(  . Writes a DR subfield(#

`	`	                                                              
`	`	  " 
   
   $         0*%%     6"|     J              <  d d                                                        %*  #  d p   @ >pQ Wm@# 
F
  Figure 6
 Sample Function Calling Sequence for a Write Application. 


#  T x    P 7QP# 
   X`	hp x (#%'0*,.8135@8:<H?A                      8pP`	hp x (#%'0*,.8135@8:<                       88 pp   OPEN USERSPECIFIED DATA MODEL AND FORMAT FILE FOR READING (INPUT)
  d B  88 pp   INVOKE beg123file() TO OPEN A FIPS PUB 123 FORMAT FILE FOR WRITING (OUTPUT)
  d B J 88 pp * INVOKE beg123ddrec() TO INITIALIZE FIPS PUB 123 DATA DESCRIPTIVE RECORD

88 pp   EXTRACT FILE TITLE FROM USERSPECIFIED FORMAT FILE
  d B < 88 pp    INVOKE wr123ddfld() TO WRITE FILE TITLE AS A DDR FIELD TO FIPS PUB 123 FILE
88 
88 pp   CREATE RECORD IDENTIFIER DESCRIPTION
  d B . 88 pp   INVOKE wr123ddfld() TO WRITE RECORD IDENTIFIER DESCRIPTION AS A DDR FIELD
88 pp     TO FIPS PUB 123 FILE 

88 pp   CREATE NODE IDENTIFIER DESCRIPTION
  d B 
 88 pp   INVOKE wr123ddfld() TO WRITE NODE IDENTIFIER DESCRIPTION AS A DDR FIELD TO
88 pp     FIPS PUB 123 FILE

88 pp   CREATE SPATIAL ADDRESS DESCRIPTION
  d B ^
 88 pp   INVOKE wr123ddfld() TO WRITE SPATIAL ADDRESS DESCRIPTION AS A DDR FIELD
88 pp     TO FIPS PUB 123 FILE

88 pp   CREATE ATTRIBUTE VALUES DESCRIPTION
  d B  88 pp   INVOKE wr123ddfld() TO WRITE ATTRIBUTE VALUES DESCRIPTION AS A DDR FIELD
88 pp     TO FIPS PUB 123 FILE

  d B  88 pp   INVOKE end123ddrec() TO END DATA DESCRIPTIVE RECORD IN FIPS PUB 123 FILE
88 
88 pp   WHILE NOT END OF FILE DO
88 pp     READ RECORD FROM USERSPECIFIED FORMAT FILE
  d B  88 pp * INVOKE beg123rec() TO INITIALIZE FIPS PUB 123 OUTPUT DATA RECORD

88 pp    EXTRACT NODE ID, SPATIAL ADDRESS, AND ATTRIBUTE VALUES FROM INPUT RECORD
  d B r 88 pp    INVOKE wr123fld() TO WRITE NODE ID AS DR FIELD TO FIPS PUB 123 FILE
  d B  88 pp    INVOKE wr123fld() TO WRITE SPATIAL ADDRESS AS DR FIELD TO FIPS PUB 123 FILE
  d B  88 pp    INVOKE wr123fld() TO WRITE ATTRIBUTE VALUES AS DR FIELD TO FIPS PUB 123
88 pp      FILE

  d B  88 pp * INVOKE end123rec() TO END DATA RECORD IN FIPS PUB 123 FILE 
88 pp     ENDWHILE

88 pp   CLOSE USERSPECIFIED FORMAT INPUT FILE
  d B H 88 pp   INVOKE end123file() TO CLOSE FIPS PUB 123 OUTPUT FILE
 $  (#(#  (#(#   '#$  0            0*%% '#O-    0  Ԓ &  x     J              xk  d d Zs  FIG_7.SWD                                            x * Zs} #  d p   @ >pQ Wm@# 
H
  Figure 7
 Sample Function Calling Sequence for a Read Application.


#  T x    P 7QP# 


  d B J              INVOKE beg123file() TO OPEN FIPS PUB 123 FORMAT FILE FOR READING (INPUT)
          OPEN USERSPECIFIED DATA MODEL AND FORMAT FILE FOR WRITING (OUTPUT)
  d B <         * INVOKE beg123ddrec() TO INITIALIZE FIPS PUB 123 DATA DESCRIPTIVE RECORD
          WHILE NOT END OF DATA DESCRIPTIVE RECORD DO
  d B .                 INVOKE rd123ddfld() TO READ A DDR FIELD
      DECODE RETURNED FIELD DESCRIPTION INTO USERSPECIFIED DATA FORMAT
      WRITE DECODED DESCRIPTION TO USER-SPECIFIED DATA FORMAT FILE
          ENDWHILE
          WHILE NOT END OF FILE DO
  d B 
      *    INVOKE beg123rec() TO INITIALIZE FIPS PUB 123 INPUT DATA RECORD
      WHILE NOT END OF RECORD DO
  d B          INVOKE rd123fld() TO READ A DR FIELD
        DECODE RETURNED FIELD DATA INTO USER-SPECIFIED DATA FORMAT
      WRITE DECODED FIELD DATA TO USER-SPECIFIED DATA FORMAT FILE
      ENDWHILE
  d B        *   INVOKE end123rec() TO END PROCESSING OF CURRENT FIPS PUB 123 DATA RECORD
          ENDWHILE
  d B            INVOKE end123file() TO CLOSE FIPS PUB 123 INPUT FILE
          CLOSE USER-SPECIFIED FORMAT OUTPUT FILE
& $  (#(#  (#(#$ '#$  0  $        0*%%  '#+    0    t T    3.2`	`	 STANDARDS AND CONVENTIONS

  t T X 3.2.1`	`	 FIPS PUB 123 Function Library

 `	`	 The FIPS PUB 123 Function Library consists of 33 applicationcallable routines.  In addition to these functions, there are 50
internal supporting routines in the software package.  All FIPS PUB
123 functions and supporting routines have '123' embedded within the
function names.(#`	

 `	`	 The current library was created to create Ccallable functions.  To
interface with other languages, all routines must be recompiled with
the appropriate option and a new library must be created.  (#`	

  t T h 3.2.2`	`	 Usage  

 `	`	 The function types and macros of the FIPS PUB 123 Function Library
  u T  are declared in the header files stc123.h and gvd123.h.  The header
  u T  file stc123.h should be included in the main application program and
in any subroutine that calls a FIPS PUB 123 function.(#`	

  u T   `	`	 Header file stc123.h contains the defined constant MAXSIZ.  This
constant places processing limitations on record, field, and
subfield sizes.  The present value of MAXSIZ is 64,000 for MSDOS
and 128,000 for other operating systems.  The software contains two
global array buffers of size MAXSIZ.  Record sizes exceeding this
limit should be processed by the field or subfield level of access. 
Fields exceeding the limit should be processed on a subfield level. 
Subfields exceeding the limit will result in failure.  (#`	


   W$         0*%%  Ԍ `	`	 Each function returns a value of 0 upon failure and a value of 1
upon success.  Many of the FIPS PUB 123 library functions also set
  u T X status indicators or accept a file option.  The valid status and
  u T  option values are defined as follows:(#`	

 `	`	   0 = failure
 `	`	   1 = okay
 `	`	   2 = start of record
 `	`	   3 = end of record
 `	`	   4 = end of file
 `	`	   5 = end of field
 `	`	   6 = start of field

  t T > 3.2.3`	`	 Bit Fields

 `	`	 FIPS PUB 123 requires that the width of a fixedlength bit field be
specified in bits, and that vectors and arrays containing fixedlength bit data have each subfield adjacent to the preceding
subfield.  The last byte of a fixedlength bit field or subfield or
a series of adjacent fixedlength bit fields or subfields should be
filled on the right with binary zeros.(#`	

  t T   `	`	 The record level read function (rd123rec()) returns bit data in a
compressed format as described above; that is, it returns each
subfield in a series of fixedlength bit subfields adjacent to the
preceding subfield.  The last byte of a fixedlength bit field or
subfield or series of subfields is filled on the right with binary
zeros.  Figure 8 depicts the compressed fixedlength bit format
within a FIPS PUB 123 data record.(#`	


   V$         0*%%   x     J              x  d d Zs  TEMP.2                                                x* Zs{ #  d p   @ >pQ Wm@# 
H
  Figure 8
L	 Compressed FixedLength Bit Data Within a Data Record.
#  d p   @ h'  V@# 

           Characters   Bits    Bits     Bits      Digits
               ab        101     01   11111 1111     12                     
 
                                          
  Q x # Fx    P 7	lFP#    ...,A(2),B(3),B(2)B(8),I(2),...         
  t T [ # 	d p   @ h'  V@#                 3        3          3       3        3
               
        
  
       	        	              
               	          	  	      
        	            
     
 


    
 
    31        3        131 11 11  3     1   31        3        13
    	0110 0001	0110 0010	1010 1111	1111 1000	0011 0001	0011 0010	 
    
 
                                         

                                          1
                                         Zero
                                         Fill   $  (#(#  (#(#'#$ 
  t T   `	`	 The field and subfield level read functions (rd123fld() and
  t T 8 rd123sfld()) return bit data in an uncompressed format.  Each
subfield in a series of fixedlength bit subfields starts on a byte
boundary.  The last byte of each fixedlength bit subfield is filled
on the right with binary zeros.  Figure 9 depicts the uncompressed
format of the data returned by field or subfield reads.(#`	

  t T @  `	`	 Similarly, the record level write function (wr123rec()) requires a
series of fixedlength bit subfields to be compressed, with each
fixedlength bit subfield adjacent to the preceding subfield and the
field zerofilled on the right to the byte boundary.  The field and
  t T # subfield write functions (wr123fld() and wr123sfld()) require a(#`	 0  #         0*%%  '#    0   !x                   <  d d Zs                                                    !   x* JZsi #  d p   @ ~rQ wl@# 
H
  Figure 9
 Uncompressed FixedLength Bit Data.


  t T  #  d p   @ h'  V@#            Characters  Bits      Bits        Bits     Digits

               ab       101       01      1111 1111     12 
     
  ^  # x&x    P 7
~xP#     ..,A(2),B(3),B(2),B(8),I(2),...     
  t T  # 
d p   @ h'  V@#                 3         3          3         3        3      
            
         	       
         	        

            	           
       	            	              	
   
 
       
        
 

  31                 1 1 1       11        1       1 1                 1
  	0110 000130110 001031010 000030100 000031111 111130011 000130011 00103 
  
 
                          
   

                            1         1
                           Zero      Zero
                           Fill      Fill
 $  (#(#  (#(#!'#$ 

 `	`	 series of fixedlength bit subfields, each subfield starting on a
byte boundary and filled on the right with binary zeros to the byte
boundary.(#`	

 `	`	 This method of processing fixedlength bit data on the field and
subfield levels facilitates the manipulation of binary data by the
applications program, since user data is usually uncompressed and
the applications programmer is most likely to process data on a
field or subfield level rather than reading or writing an entire
data record.(#`	
 0  $!         0*%%  '#  !! 0    t T    3.3`	`	 FUNCTION DESCRIPTIONS

 `	`	 This section provides a concise description of each FIPS PUB 123
function organized by usage as follows:(#`	

  t T   `	`	  X o X" Begin/End functionsinitialize and terminate file, DDR,
and DR processing(#

  t T `	  `	`	  X o X" Read functionsread DDR and DR on record, field, and
subfield level(#

  t T   `	`	  X o X" Write functionswrite DDR and DR on record, field, and
subfield level(#

  t T h  `	`	  X o X" Backup functionsback up the currency pointers for the
DR record on a record, field, or subfield level(#

  t T   `	`	  X o X" Check functionsretrieve the DDR description of a
record, field, or subfield(#

  t T p  `	`	  X o X" Erase functionserase the last DDR record, field, or
subfield written(#
 
  t T   `	`	  X o X" Utility functionsinclude support functions for
processing binary data.(#
 `	`	  X (#
 `	`	 The programmer should be familiar with basic programming concepts
such as function parameter variables, passby value, and passby
reference.  Recursive use of library functions is not encouraged;
however, multiple iterative invocations are allowed.(#`	

   T$"         0*%%  Ԍ  t T    3.3.1 `	`	 Begin/End Functions(#`	

 `	`	 The FIPS PUB 123 Function Library begin and end functions are called
to initiate or to terminate processing of a FIPS PUB 123 data
descriptive file, a data descriptive record, or a data record. 
These functions include:(#`	

  t T 4  `	`	  X o X" beg123ddrec()ĩinitiates DDR processing(#
  t T `	  `	`	  X o X" beg123file()ĩinitiates processing of a DDF(#
  t T 
  `	`	  X o X" beg123rec()ĩinitiates processing of a DR (#
  t T   `	`	  X o X" end123ddrec()ĩterminates DDR processing (#
  t T   `	`	  X o X" end123file()ĩterminates processing of the DDF (#
  t T   `	`	  X o X" end123rec()ĩterminates processing of a DR.(#

  t T h  `	`	 Use of the functions beg123file() and end123file() is mandatory for
  t T  all DDFs whether opened in 'read' or 'write' mode.  end123ddrec()
  t T  and end123rec() are required for files opened in 'write' mode;
  t T  however end123rec() is optional when immediately followed by a call
  t T  to end123file(). (#`	
    D#         0*%%    u T                       ~    Zs  t T    # d p   @ >pQ Wm@# `	`	  " hh( . 3 pp9 ?   E beg123ddrec              X`	hp x (#%'0*,.8135@8:<H?A                      X `	hp x (#%'0*,.8135@8:<H?A                     Function Name:  beg123ddrec(#

  u T  Purpose: `	`	 To begin the data descriptive record.(#`	

  u T " Arguments: `	`	 beg123ddrec(*fp)(#`	

  u S     Input:

  t T C    `	`	 Name           hh( Type      3 Description

  t T     `	`	 fp             hh( *FILE     3 file pointer

  u T c	    Output: none

  u S 
    Returns:

  t T   p    `	`	 Name          hh( Type      3 Description(# 

  t T   p   `	`	 beg123ddrec()hh( int        
3 success flag, returns 1 if
successful or 0 if error  (#

  u S l External References:" stc123.h

  u T     Requirements:  Use of function beg123ddrec() is optional to begin data
descriptive record processing prior to reading or writing a
data descriptive record.  After the data descriptive record
  t T U has been written, end123ddrec() must be called to end
processing.(#

  u T  Processing: `	`	  X Function beg123ddrec() begins processing of a data descriptive
  t T v record for file pointer fp and removes all previous DDR data
  t T > for file pointer fp from memory.(#
    $         0*%%    u T      ~               U    3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E beg123file     Function Name:  beg123file(#

  u T  Purpose: `	`	 To open a FIPS PUB 123 data descriptive file for reading or
writing. (#`	

  u T  Arguments: `	`	 beg123file (*f_name,mode,*int_level,*ice,*ccs,**fp)(#`	

  u S {    Input:

  t T     `	`	 Name          hh( Type      3 Description

  t T     `	`	 f_name[]      hh( *char     3 file name
  t T c	    `	`	 mode          hh( char      3 mode:pp9 'w' = write
   `	`	  " hh( . 3 pp9 'r' = read
  t T 
    `	`	 int_level     hh( *long     3 interchange level:  1, 2, or 3
  t T     `	`	 ice[]         hh( *char     3 inline code extension indicator:
  t T     `	`	  " hh( . 3 ' '  pp9 no inline escape sequences are
used to designate extended
coded character sets(#p
  t T     `	`	  " hh( . 3 'E'  pp9 extensions are used as
specified in ISO 2022(#p
  t T k    `	`	 ccs[]         hh( *char     3 code character set indicator:
   `	`	  " hh( . 3 "   "  (3 spaces) the
   `	`	  " hh( . 3 pp9   International Reference
   `	`	  " hh( . 3 pp9   Version of the ISO 646
   `	`	  " hh( . 3 pp9   character set is the default
   `	`	  " hh( . 3 pp9   for the file; refer to ISO
   `	`	  " hh( . 3 pp9   8211 for other values

  u S     Output:

  t T ;     `	`	 Name          hh( Type      3 Description

  t T     `	`	 int_level     hh( *long     3 interchange level:  1, 2, or 3
  t T     `	`	 ice[]         hh( *char     3 inline code extension indicator:
  t T [    `	`	  " hh( . 3 ' '  pp9 no inline escape sequences are
used to designate extended
coded character sets(#p
  t T     `	`	  " hh( . 3 'E'  pp9 extensions are used as
specified in ISO 2022(#p
  t T C    `	`	 ccs[]         hh( *char     3 code character set indicator:
   `	`	  " hh( . 3 "   "  (3 spaces) the
   `	`	  " hh( . 3 pp9   International Reference
   `	`	  " hh( . 3 pp9   Version of the ISO 646
   `	`	  " hh( . 3 pp9   character set is the default
   `	`	  " hh( . 3 pp9   for the file; refer to ISO
   `	`	  " hh( . 3 pp9   8211 for other values   #%         0*%%  Ԍ  t T       `	`	 fp            hh( **FILE    3 file pointer

  u S     Returns:

  t T      `	`	 Name          hh( Type      3 Description

  t T     `	`	 beg123file()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S  External References:" stc123.h

  u T     Requirements:  Function beg123file() must be called to open and begin
  t T a	 processing of a FIPS PUB 123 DDF.  Parameters int_level, ice,
  t T )
 and ccs must be input when opening files in 'write' mode. 
  t T 
 Function end123file() must be called to end processing of the
data file.(#

  u T I
 Processing: `	`	  X Function beg123file() opens a data file in 'read' or 'write'
  t T  mode based on the input parameter mode.  The interchange level
  t T  int_level, inline code extension ice, and code character set
  t T  ccs are returned by beg123file() for files opened in 'read'
  t T j mode.  Parameters int_level, ice, and ccs must be input when
opening files in 'write' mode.(#   2&        0*%%    u T      U                   3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E beg123rec      Function Name:  beg123rec(#

  u T  Purpose: `	`	 To begin a data record.(#`	

  u T " Arguments: `	`	 beg123rec (*fp)(#`	

  u S     Input:

  t T C     `	`	 Name         hh( Type      3 Description

  t T     `	`	 fp           hh( *FILE     3 file pointer

  u T c	    Output: none

  u S 
    Returns:

  t T     `	`	 Name        hh( Type      3 Description

  t T     `	`	 beg123rec()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S l External References:" stc123.h

  u T     Requirements:  Function beg123rec() is an optional function that may be
invoked by the application to initiate processing of a new DR. 
(#

  u T  Processing: `	`	  X Function beg123rec() begins processing of a DR.  Processing of
  t T  a previous DR not already ended by end123rec() is ended by
  t T  beg123rec() before processing of the next DR begins.  The
supporting functions will invoke this optional function as
required.(#
   '         0*%%    u T                         3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E end123ddrec     Function Name:  end123ddrec(#

  u T  Purpose: `	`	 To end the data descriptive record.(#`	

  u T " Arguments: `	`	 end123ddrec (*fp)(#`	

  u S     Input:

  t T C    `	`	 Name           hh( Type      3 Description

  t T     `	`	 fp            hh( **FILE     3 file pointer

  u T c	    Output: none

  u S 
    Returns:

  t T     `	`	 Name           hh( Type      3 Description

  t T     `	`	 end123ddrec()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S l External References:" stc123.h

  u T     Requirements:  For a file opened in 'write' mode, function end123ddrec() must
be invoked upon completion of all write DDR functions and
before processing the first DR. This function has no effect on
a file opened in 'read' mode.(#

  u T  Processing: `	`	  X Function end123ddrec() ends processing of a data descriptive
record.  The function computes the leader and directory and
  t T v writes the DDR to file fp. (#
   >(         0*%%    u T                     2    3  t T       # d p   @ >pQ Wm@# `	`	  " hh( . 3 pp9 ?   E end123file     Function Name:  end123file(#

  u T  Purpose: `	`	 To close a FIPS PUB 123 data descriptive file.  (#`	

  u T " Arguments: `	`	 end123file (*fp)(#`	

  u S     Input:

  t T C    `	`	 Name           hh( Type      3 Description

  t T     `	`	 fp             hh( *FILE     3 file pointer

  u T c	    Output: none

  u S 
    Returns:

  t T     `	`	 Name           hh( Type      3 Description

  t T     `	`	 end123file()   hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S l External References:" stc123.h

  u T     Requirements:  Function end123file() must be called to end processing and
properly close any DDF previously opened by a call to
  t T  beg123file() in either 'read' or 'write' mode.(#

  u T  Processing: `	`	  X Function end123file() ends processing and closes the data
file.  For a file opened in 'write' mode, any DR currently in
memory is written to the output DDF.  All current data
  t T v structures for fp are freed.(#
   >)         0*%%    u T      2                   3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E end123rec     Function Name:  end123rec(#

  u T  Purpose: `	`	 To end processing of a data record.(#`	

  u T " Arguments: `	`	 end123rec (*fp)(#`	

  u S     Input:

  t T C    `	`	 Name         hh( Type      3 Description

  t T     `	`	 fp           hh( *FILE     3 file pointer

  u T c	    Output: none

  u S 
    Returns:

  t T     `	`	 Name         hh( Type      3 Description

  t T     `	`	 end123rec()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S l External References:" stc123.h

  u T     Requirements:  Function end123rec() is an optional function that may be
invoked to terminate processing of the current DR.  (#

  u T U Processing: `	`	  X Function end123rec() ends processing of a DR.  The current DR
is written to the output DDF and internal DRrelated
structures are freed.  The supporting functions will invoke
this optional function as required.(#
   v*         0*%%    t T              G           3# d p   @ >pQ Wm@# `(#(#V G      3.3.2 p    @`	`	 Read Functions(#`	

 p    @`	`	 The FIPS PUB 123 Function Library read functions provide flexibility
to the applications programmer in processing the DDF.  Functions are
provided to read both the DDR and the DR on a record level, field
level, or subfield level.  Very large DRs or DRs containing complex
structures 

may require processing at the field or subfield level. 
The FIPS PUB 123 Function Library read functions include:(#`	

  t T 
  p    @`	`	  X o X" rd123ddfld()ĩreads the next field of the DDR(#

  t T   p    @`	`	  X o X" rd123ddrec()ĩreads the complete DDR, including leader
and directory(#

  t T h  p    @`	`	  X o X" rd123ddsfld()ĩreads the next subfield of the DDR(#

  t T   p    @`	`	  X o X" rd123fld()ĩreads the next DR field (#

  t T   p    @`	`	  X o X" rd123rec()ĩreads the next DR, including leader and
directory(#

  t T   p    @`	`	  X o X" rd123sfld()ĩreads the next DR subfield. (#

 p    @`	`	 The usage of these functions is described in the following
paragraphs.  To facilitate DR processing, the 'check' functions may
be used to query the DDR and retrieve the format and description of
the current record, field, subfield, or the next record, field, or
subfield.(#`	
    +         0*%%    u T                     ͜    0  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E rd123ddfld        Function Name:  rd123ddfld(#

  u T  Purpose: `	`	 To read a field of the data descriptive record.(#`	

  u T " Arguments: `	`	 rd123ddfld (*fp,*tag,*rd_str,*status)(#`	

  u S     Input:

  t T C  p    `	`	 Name          hh( Type      3 Description(# 

  t T   p    `	`	 fp            hh( *FILE     3 file pointer(# 

  u S c	    Output:

  t T 
     `	`	 Name          hh( Type      3 Description

  t T     `	`	 tag[]        hh( *char     3 field tag

  t T     `	`	 rd_str[]      hh( *char      h3 string consisting of concatenated
subfields of current DDR field(#

  t T k    `	`	 status        hh( *int      3 status
   `	`	  " hh( . 3 0 = failure
   `	`	  " hh( . 3 3 = end of record
   `	`	  " hh( . 3 4 = end of file
   `	`	  " hh( . 3 5 = end of field

  u S     Returns:

  t T   p    `	`	 Name          hh( Type      3 Description(# 

  t T ;  p    `	`	 rd123ddfld()  hh( int        
3 success flag, returns 1 if
successful or 0 if error(#

  u S  External References:" stc123.h

  u T #    Requirements:  Use rd123ddfld() on DDFs opened in 'read' mode.  Parameter
  t T  rd_str must be declared as a character string large enough to
hold the entire DDR field.(#

  u T D Processing: `	`	  X Function rd123ddfld() reads the current DDR field from a file
  t T 
  opened in 'read' mode and returns the field in rd_str.(#   
 ,        0*%%    u T      ͜                   3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E xxK rd123ddrec      Function Name:  rd123ddrec(#

  u T  Purpose: `	`	 To read the complete data descriptive record.(#`	

  u T " Arguments: `	`	 rd123ddrec (*fp,*string,*status)(#`	

  u S     Input:

  t T C    `	`	 Name          hh( Type      3 Description

  t T     `	`	 fp            hh( *FILE     3 file pointer

  u S c	    Output:

  t T 
    `	`	 Name          hh( Type      3 Description

  t T     `	`	 string[]      hh( *char .  X3 string containing complete DDR,
including leader and directory(#

  t T     `	`	 status        hh( *int      3 status
   `	`	  " hh( . 3 0 = failure
   `	`	  " hh( . 3 3 = end of record
   `	`	  " hh( . 3 4 = end of file

  u S     Returns:

  t T S     `	`	 Name          hh( Type      3 Description

  t T     `	`	 rd123ddrec()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S ; External References:" stc123.h

  u T     Requirements:  Use rd123ddrec() on files opened in 'read ' mode.  Parameter
  t T  string must be declared as a character string large enough to
hold the entire data descriptive record.  Do not use
  t T $ rd123ddrec() for a data descriptive record that is expected to
  u T  exceed a length of MAXSIZ.  Use rd123ddfld() and rd123ddsfld()
since data descriptive record fields and subfields are less
  u T } likely to exceed MAXSIZ bytes in length.  See paragraph 3.2.2
  u T F for information on MAXSIZ.(#

  u T   Processing: `	`	  X Function rd123ddrec() reads a complete data descriptive
record, populates the appropriate internal FIPS PUB 123 data
  t T h" structures, and returns the record in string.  (#
   0#-         0*%%    u T                     l    3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E rd123ddsfld     Function Name:  rd123ddsfld (#

  u T  Purpose: `	`	 To read a subfield of the data descriptive record. (#`	

  u T " Arguments: `	`	 rd123ddsfld (*fp,*tag,*rd_str,*status)(#`	

  u S     Input:

  t T C    `	`	 Name           hh( Type      3 Description

  t T     `	`	 fp             hh( *FILE     3 file pointer

  u S c	    Output:

  t T 
    `	`	 Name           hh( Type      3 Description

  t T     `	`	 tag[]        hh( *char     3 field tag
  t T K
    `	`	 rd_str[]       hh( *char     3 subfield string
  t T     `	`	 status         hh( *int      3 status
   `	`	  " hh( . 3 0 = failure
   `	`	  " hh( . 3 1 = okay
   `	`	  " hh( . 3 2 = start of record
   `	`	  " hh( . 3 3 = end of record
   `	`	  " hh( . 3 4 = end of file
   `	`	  " hh( . 3 5 = end of field
   `	`	  " hh( . 3 6 = start of field

  u S     Returns:

  t T     `	`	 Name           hh( Type      3 Description

  t T ;    `	`	 rd123ddsfld()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S  External References:" stc123.h

  u T #    Requirements:  Use rd123ddsfld() on DDFs opened in 'read' mode.  Parameter
  t T  rd_str must be declared as a character string large enough to
hold the DDR subfield.(#

  u T D Processing: `	`	  X Function rd123ddsfld() retrieves the next DDR subfield from a
  t T 
  DDF opened in 'read' mode and returns the result in rd_str.(#
    .         0*%%    u T      l               Ǫ    3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E rd123fld     Function Name:  rd123fld(#

  u T  Purpose: `	`	 To read a field of a data record.(#`	

  u T " Arguments: `	`	 rd123fld (*fp,*tag,*leadid,*rd_str,*str_len,*status)(#`	

  u S     Input:

  t T C    `	`	 Name        hh( Type      3 Description

  t T     `	`	 fp          hh( *FILE     3 file pointer

  u S c	    Output:

  t T 
    `	`	 Name        hh( Type      3 Description

  t T     `	`	 tag[]       hh( *char     3 field tag
  t T K
    `	`	 leadid[]   " hh( *char     3 leader identifier
  t T     `	`	 rd_str[]    hh( *char     3 string containing field read
  t T     `	`	 str_len     hh( *long     3 byte length of rd_str
  t T     `	`	 status      hh( *int      3 status
   `	`	  " hh( . 3 0 = failure
   `	`	  " hh( . 3 1 = okay
   `	`	  " hh( . 3 2 = start of record
   `	`	  " hh( . 3 3 = end of record
   `	`	  " hh( . 3 4 = end of file 

  u S     Returns:

  t T     `	`	 Name        hh( Type      3 Description

  t T ;    `	`	 rd123fld()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S  External References:" stc123.h

  u T #    Requirements:  Use rd123fld() to read a field from a DDF opened in 'read'
  t T  mode.   The parameter rd_str must be defined as a character
string large enough to hold the field value.  Note:  a fixedlength bit field or a field containing fixedlength bit
subfields is returned in uncompressed format.  Ensure that
  t T   rd_str is sufficiently large to contain the entire
uncompressed string.(#



   #/         0*%%  Ԍ  u T    Processing: `	`	  X Function rd123fld() retrieves the next DR field in file fp. 
  t T   The field is returned as a character string in rd_str with
concatenated subfields.  (#   0        0*%%    u T      Ǫ               @    3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E rd123recĻ    Function Name:  rd123rec(#

  u T  Purpose: `	`	 To read a complete data record, including leader and directory.(#`	

  u T " Arguments: `	`	 rd123rec (*fp,*string,*str_len,*status)(#`	

  u S     Input:

  t T C    `	`	 Name        hh( Type      3 Description

  t T     `	`	 fp          hh( *FILE     3 file pointer

  u S c	    Output:

  t T 
    `	`	 Name        hh( Type      3 Description

  t T     `	`	 string[]    hh( *char .  X3 string containing record read,
including leader and directory    (#

  t T     `	`	 str_len     hh( *long     3 length of string

  t T k    `	`	 status      hh( *int      3 status
   `	`	  " hh( . 3 0 = failure
   `	`	  " hh( . 3 1 = okay
   `	`	  " hh( . 3 4 = end of file

  u S S    Returns:

  t T     `	`	 Name        hh( Type      3 Description

  t T s    `	`	 rd123rec()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S  External References:" stc123.h

  u T [    Requirements:  Use rd123rec() to read an entire data record from a DDF opened
  t T $ in 'read' mode.  The parameter string must be declared as a
character string large enough to hold the entire DR.  Do not
  t T  use rd123rec() for a DR that is expected to exceed a length of
  u T | MAXSIZ.  Use rd123fld() and rd123sfld() since DR fields and
  u T E subfields are less likely to exceed MAXSIZ bytes in length. 
  u T   See paragraph 3.2.2 for information on MAXSIZ.(#

  u T ! Processing: `	`	  X Function rd123rec() reads the next DR from file fp and returns
  t T h" the record in string.  Adjacent fixedlength bit
fields/subfields are returned in compressed format. (#
   #1         0*%%    u T      @                   3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E rd123sfldļ    Function Name:  rd123sfld (#

  u T  Purpose: `	`	 To read a subfield of a data record. (#`	

  u T " Arguments: `	`	 rd123sfld (*fp,*tag,*leadid,*rd_str,*str_len,*status) (#`	

  u S     Input:

  t T C    `	`	 Name       " hh( Type      3 Description 

  t T     `	`	 fp         " hh( *FILE     3 file pointer 

  u S c	    Output:

  t T 
    `	`	 Name       " hh( Type      3 Description 

  t T     `	`	 tag[]      " hh( *char     3 field tag
  t T K
    `	`	 leadid[]   " hh( *char     3 leader identifier 
  t T     `	`	 rd_str[]   " hh( *char      h3 subfield string (#
  t T     `	`	 str_len    " hh( *long     3 byte length of rd_str
  t T     `	`	 status     " hh( *int      3 status 
   `	`	  " hh( . 3 0 = failure 
   `	`	  " hh( . 3 1 = okay 
   `	`	  " hh( . 3 2 = start of record 
   `	`	  " hh( . 3 3 = end of record 
   `	`	  " hh( . 3 4 = end of file 
   `	`	  " hh( . 3 5 = end of field 
   `	`	  " hh( . 3 6 = start of field 

  u S     Returns:

  t T ;    `	`	 Name       " hh( Type      3 Description 

  t T     `	`	 rd123sfld() hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S # External References:" stc123.h

  u T     Requirements:  Use rd123sfld() to read a subfield from a DDF opened in 'read'
  t T | mode.  The parameter rd_str must be declared as a character
string large enough to hold the DR subfield.(#

  u T   Processing: `	`	  X Function rd123sfld() retrieves the next DR subfield from file
  t T ! fp and returns the result in rd_str. (#   !2        0*%%    t T                      g    3`(#(#V        3.3.3 p    @`	`	 Write Functions(#`	

 p    @`	`	 The FIPS PUB 123 Function Library write functions provide
flexibility to the applications programmer in creating a DDF. 
Functions are provided to write both the DDR and the DR on a record
level, field level, or subfield level.  Very large DRs or DRs
containing complex structures 

may require processing at the field or
subfield level.  The FIPS PUB 123 Function Library write functions
include:(#`	

  t T   p    @`	`	  X o X" wr123ddfld()ĩwrites a DDR field(#

  t T   p    @`	`	  X o X" wr123ddrec()ĩaccepts a string containing the complete
DDR, including leader and directory, and writes the DDR
to the output file(#

  t T   p    @`	`	  X o X" wr123ddsfld()ĩwrites a DDR subfield (#

  t T   p    @`	`	  X o X" wr123fld()ĩwrites a DR field (#

  t T p  p    @`	`	  X o X" wr123rec()ĩwrites a complete DR, including leader and
directory(#

  t T   p    @`	`	  X o X" wr123sfld()ĩwrites a DR subfield. (#

 p    @`	`	 The usage of these functions is described in the following
paragraphs.(#`	

    3         0*%%    u T      g                   0  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E wr123ddfld        Function Name:  wr123ddfld (#

  u T  Purpose: `	`	 To write a field to the data descriptive record.(#`	

  u T " Arguments: `	`	 wr123ddfld (*fp,*tag,*wr_str,option)(#`	

  u S     Input:

  t T C    `	`	 Name          hh( Type     3 Description

  t T     `	`	 fp            hh( *FILE    3 file pointer
  t T     `	`	 tag[]         hh( *char    3 field tag
  t T c	    `	`	 wr_str[]      hh( *char    3 string containing a DDR field
  t T +
    `	`	 option        hh( int      3 write field option
   `	`	  " hh( . 3 1 = okay
   `	`	  " hh( . 3 2 = start of record
   `	`	  " hh( . 3 3 = end of record
   `	`	  " hh( . 3 4 = end of file 

  u T     Output: none

  u S l    Returns:

  t T     `	`	 Name          hh( Type     3 Description

  t T     `	`	 wr123ddfld()  hh( int       h3 success flag, returns 1 if
successful or 0 if error(#

  u S  External References:" stc123.h

  u T t    Requirements:  Use wr123ddfld() to write a DDR field to a DDF opened in
'write' mode.  The first field of the DDR must be written
using the 'start of record' option.  Subsequent fields must be
written using the 'okay' option and the last field must be
written using the 'end of record' or 'end of file' option.(#

  u T % Processing: `	`	  X Function wr123ddfld() writes the DDR field contained in wr_str
  t T  to the file fp. (#
   4         0*%%    u T                     T    3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E wr123ddrecĽ    Function Name:  wr123ddrec(#

  u T  Purpose: `	`	 To write a complete data descriptive record, including leader and
directory.(#`	

  u T  Arguments: `	`	 wr123ddrec (*fp,*string,*status)(#`	

  u S {    Input:

  t T     `	`	 Name          hh( Type      3 Description

  t T     `	`	 fp            hh( *FILE     3 pointer to file pointer

  t T +
    `	`	 string[]      hh( *char .  X3 string containing the complete DDR,
including leader and directory(#

  u S     Output:

  t T     `	`	 Name          hh( Type      3 Description

  t T     `	`	 status        hh( *int      3 status
  t T k                                 3 0 = failure
   `	`	  " hh( . 3 1 = okay

  u S     Returns:

  t T S    `	`	 Name          hh( Type      3 Description

  t T     `	`	 wr123ddrec()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S ; External References:" stc123.h

  u T     Requirements:  Use wr123ddrec() to write a complete DDR of a DDF opened in
  t T  'write' mode.  The parameter status is set to 'failure' if an
  t T \ error is encountered during processing.  Follow wr123ddrec
  t T $ with a call to end123ddrec to end processing of the DDR.(#

  u T  Processing: `	`	  X Function wr123ddrec() writes the string contained in wr_str to
  t T } file fp.  It then backs up and rereads the DDR to correctly
populate the FIPS PUB 123 internal data structures.(#
   
 5         0*%%    u T      T                   3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E wr123ddsfld     Function Name:  wr123ddsfld (#

  u T  Purpose: `	`	 To write a subfield to the data descriptive record.(#`	

  u T " Arguments: `	`	 wr123ddsfld (*fp,*tag,*wr_str,option)(#`	

  u S     Input:

  t T C    `	`	 Name           hh( Type      3 Description

  t T     `	`	 fp             hh( *FILE     3 file pointer
  t T     `	`	 tag[]        hh( *char     3 field tag
  t T c	    `	`	 wr_str[]       hh( *char     3 string containing a DDR field
  t T +
    `	`	 option         hh( int       3 write subfield option
   `	`	  " hh( . 3 1 = okay
   `	`	  " hh( . 3 2 = start of record
   `	`	  " hh( . 3 3 = end of record
   `	`	  " hh( . 3 4 = end of file 
   `	`	  " hh( . 3 5 = end of field
   `	`	  " hh( . 3 6 = start of field

  u T k    Output: none

  u S     Returns:

  t T     `	`	 Name           hh( Type      3 Description

  t T     `	`	 wr123ddsfld()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S t External References:" stc123.h

  u T     Requirements:  Use wr123ddsfld() to write a DDR subfield to a DDF opened in
'write' mode.  The first subfield of the data descriptive
record must be written using the 'start of record' option. 
Each subsequent subfield thnat is also the start of a field
must be written with the 'start of field' option; each
subsequent subfield that is also the last subfield of a field
must be written with the 'end of field' option.  Subfields
within a field which are neither the first or last subfield of
the field must be written using the 'okay' option.  The last
subfield of the DDR must be written with the 'end of record'
option if data records are to follow; if no data records are
to be written at this time, it must be written using the 'end
of file' option.(#

  u T # Processing: `	`	  X Function wr123ddsfld() writes a DDR subfield to file fp. (#   #6         0*%%    u T                     P    3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E wr123fldĻ    Function Name:  wr123fld (#

  u T  Purpose: `	`	 To write a field to a data record.(#`	

  u T " Arguments: `	`	 wr123fld (*fp,*tag,leadid,*wr_str,*str_len,*option)(#`	

  u S     Input:

  t T C    `	`	 Name        hh( Type      3 Description

  t T     `	`	 fp          hh( *FILE     3 file pointer
  t T     `	`	 tag[]       hh( *char     3 field tag
  t T c	    `	`	 leadid      hh( char     3 leader identifier: 'D' or 'R'
  t T +
    `	`	  " hh( . 3 'D'  pp9 a leader and directory will be
found in subsequent DR(#p
  t T     `	`	  " hh( . 3 'R'  pp9 the leader and directory will
not be found in subsequent
DRs; the leader and directory
of the current DR will apply
to subsequent DRs(#p
  t T     `	`	 wr_str[]    hh( *char     3 string containing a DR field
  t T k    `	`	 str_len     hh( long     3 length of wr_str
  t T 3    `	`	 option      hh( int      3 write field option
   `	`	  " hh( . 3 1 = okay 
   `	`	  " hh( . 3 2 = start of record 
   `	`	  " hh( . 3 3 = end of record 
   `	`	  " hh( . 3 4 = end of file 

  u T     Output: none

  u S t    Returns:

  t T     `	`	 Name        hh( Type      3 Description

  t T     `	`	 wr123fld()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S  External References:" stc123.h

  u T |    Requirements:  Use wr123fld() to write a field to a DR for a DDF opened in
'write' mode.  The first field must be written using the
'start of record' option.  Subsequent fields of the DR must be
written using the 'okay' option and the last field must be
written using the 'end of record' option.  The last field of
the DDF must be written using the 'end of file' option.(#

   #7         0*%%  Ԍ  t T       `	`	   Once a leader ID (leadid) of 'R' is used, it should continue
to be used throughout the rest of the file when writing by
fields or subfields.(#

  u T   Processing: `	`	  X Function wr123fld() writes a DR field to file fp.(#
   8         0*%%    u T      P                   3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E wr123recĻ    Function Name:  wr123rec(#

  u T  Purpose: `	`	 To write a complete data record, including leader and directory.(#`	

  u T " Arguments: `	`	 wr123rec (*fp,*string,*str_len,*status)(#`	

  u S     Input:

  t T C    `	`	 Name          hh( Type      3 Description

  t T     `	`	 fp            hh( *FILE     3 file pointer

  t T c	    `	`	 string[]      hh( *char .  X3 string containing complete data
record, including leader and
directory(#

  t T     `	`	 str_len       hh( *long     3 length of string 

  u S     Output:

  t T     `	`	 Name          hh( Type      3 Description

  t T 3    `	`	 status        hh( *int      3 status
   `	`	  " hh( . 3 0 = failure
   `	`	  " hh( . 3 1 = okay

  u S S    Returns:

  t T     `	`	 Name          hh( Type      3 Description

  t T s    `	`	 wr123rec()    hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S  External References:" stc123.h

  u T [    Requirements:  Use wr123rec() to write an entire data record to a DDF opened
in 'write' mode.  (#

  u T  Processing: `	`	  X Function wr123rec() writes the DR contained in string to file
  t T } fp.  A status of 'failure' is returned if an error is
encountered during processing. (#   E9        0*%%    u T                         3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E wr123sfldļ    Function Name:  wr123sfld (#

  u T  Purpose: `	`	 To write a subfield of a data record. (#`	

  u T " Arguments: `	`	 wr123sfld (*fp,*tag,leadid,*wr_str,*str_len,*option) (#`	

  u S     Input:

  t T C    `	`	 Name       " hh( Type      3 Description 

  t T     `	`	 fp         " hh( *FILE     3 file pointer 
  t T     `	`	 tag[]    " hh( *char     3 field tag
  t T c	    `	`	 leadid     " hh( char     3 leader identifier
  t T +
    `	`	  " hh( . 3 'D'  pp9 a leader and directory will be
found in subsequent DR(#p
  t T     `	`	  " hh( . 3 'R'  pp9 the leader and directory will
not be found in subsequent
DRs; the leader and directory
of the current DR will apply
to subsequent DRs(#p
  t T     `	`	 wr_str[]   " hh( *char      h3 string containing a DR subfield (#
  t T k    `	`	 str_len    " hh( *long     3 length of wr_str
  t T 3    `	`	 option     " hh( *int      3 write subfield option 
   `	`	  " hh( . 3 1 = okay 
   `	`	  " hh( . 3 2 = start of record 
   `	`	  " hh( . 3 3 = end of record 
   `	`	  " hh( . 3 4 = end of file
   `	`	  " hh( . 3 5 = end of field  
   `	`	  " hh( . 3 6 = start of field   

  u T s    Output: none

  u S     Returns:

  t T     `	`	 Name       " hh( Type     3 Description 

  t T $    `	`	 wr123sfld() hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S | External References:" stc123.h

  u T      Requirements:  Use wr123sfld() to write a subfield to a DR for a DDF opened
in 'write' mode.  The first subfield of the DR must be written
using the 'start of record' option.  Each subsequent subfield
that is also the start of a field must be written with the
"start of field" option; each subsequent subfield that is also
the last subfield of a field must be written with the 'end of   #:        0*%%  field' option.  Subfields within a field which are neither the
first or last subfield of the field must be written using the
'okay' option.  The last subfield of the DR must be written
with the 'end of record' option; if this is the last DR to be
written, the last subfield must be written with the 'end of
file' option. (#

  t T x    `	`	   Once a leader ID (leadid) of 'R' is used, it should continue
to be used throughout the rest of the file when writing by
fields or subfields. (#
 
  u T  Processing: `	`	  X Function wr123sfld() writes the DR subfield contained in
  t T a	 wr_str to file fp.  (#
   )
;         0*%%    t T              G           3# d p   @ >pQ Wm@# `(#(#V G      3.3.4 p    @`	`	 Backup Functions(#`	

 p    @`	`	 The FIPS PUB 123 Function LIbrary backup functions may be used to
change the currency pointers of a DDF being processed to a
previously processed data record, DR field, or DR subfield.  For a
DDF opened in 'write' mode, the current record/field/subfield is
erased as the currency pointer is backed up.  An example of usage of
a backup function would be to backup and rewrite a record, field,
  t T `	 or subfield with an 'end of file' option upon detecting an 'end of
file' condition on the input userspecified data model.(#`	

  t T   p     @`	`	 The backup functions include the following:(#`	

  t T <  p    @`	`	  X o X" bak123fld()ĩbacks up the currency pointer to the
beginning of the last field read or written(#

  t T   p    @`	`	  X o X" bak123rec()ĩbacks up the currency pointer to the
beginning of the last record read or written(#

  t T D  p    @`	`	  X o X" bak123sfld()ĩBacks up the currency pointer to the last
subfield read or written.(#

 p    @`	`	 To facilitate applications processing, the 'check' functions may be
used to query the DDR and retrieve the format and description of the
new current record, field or subfield, or the next record, field or
subfield.(#`	

 p    @`	`	 The following paragraphs describe the usage of these functions.(#`	   <         0*%%    u T                     ;    0  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E bak123fldļ       Function Name:  bak123fld (#

  u T  Purpose: `	`	 To back up to the beginning of the last DR field read or written. (#`	

  u T " Arguments: `	`	 bak123fld (*fp,*status)(#`	

  u S     Input:

  t T C    `	`	 Name         hh( Type      3 Description

  t T     `	`	 fp           hh( *FILE     3 file pointer

  u S c	    Output:

  t T 
    `	`	 Name  " hh( Type. 3 Description

  t T     `	`	 status       hh( *int     3 status
   `	`	  " hh( . 3 0 = failure
   `	`	  " hh( . 3 1 = okay
   `	`	  " hh( . 3 2 = start of record
   `	`	  " hh( . 3 3 = end of record

  u S 3    Returns:

  t T     `	`	 Name         hh( Type      3 Description

  t T S    `	`	 bak123fld()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S  External References:" stc123.h

  u T ;    Requirements:  Reading or writing a DR or any part of a DR within a file must
occur prior to backing up within the file.(#

  u T  Processing: `	`	  X Function bak123fld() backs up to the beginning of the last
  t T ] field read or written for file fp.  For a DDF opened in
  t T % 'write' mode, bak123fld() deletes the current field, modifies
the field pointer to the end of the previous field, and
  t T  returns the new position in status.  (#

 p    @`	`	  X For a DDF opened in 'read' mode, the field pointer is backed
up to the beginning of the current field and the new position
  t T   is returned in status.  This field may now be reread.(#

  t T e"  p    @`	`	  X A status of 'failure' is returned when backing up while
positioned at the first DR field in a DDF.(#   -#=        0*%%    u T      ;               j    3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E bak123recļ    Function Name:  bak123rec  (#

  u T  Purpose: `	`	 To back up to the beginning of the last DR read or written.(#`	

  u T " Arguments: `	`	 bak123rec (*fp,*status)(#`	

  u S     Input:

  t T C    `	`	 Name " hh( Type. 3 Description

  t T     `	`	 fp           hh( *FILE     3 file pointer

  u S c	    Output:

  t T 
    `	`	 Name " hh( Type. 3 Description

  t T     `	`	 status       hh( *int      3 status
   `	`	  " hh( . 3 0 = failure
   `	`	  " hh( . 3 1 = okay

  u S     Returns:

  t T 3    `	`	 Name        hh( Type      3 Description

  t T     `	`	 bak123rec()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S  External References:" stc123.h

  u T     Requirements:  Reading or writing a DR or any part of a DR within a file must
occur prior to backing up within the file.(#

  u T  Processing: `	`	  X Function bak123rec() backs up to the beginning of the last DR
  t T  read or written for file fp.  For a DDF opened in "write"
  t T  mode, bak123rec() deletes the current record, sets the record
pointer to the start of the record, and returns the
  t T % appropriate position in status.  For a file opened in 'read'
mode, the record pointer is backed up to the start of the
  t T  current record and the status is returned 'okay'.  A status of
'failure' is returned when backing up while positioned at the
first record in a data file.  (#   E>        0*%%    u T      j                    3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E bak123sfldĽ    Function Name:  bak123sfld (#

  u T  Purpose: `	`	 To back up to the beginning of the last DR subfield read or
written.(#`	

  u T  Arguments: `	`	 bak123sfld (*fp,*status) (#`	

  u S {    Input:

  t T     `	`	 Name          hh( Type      3 Description

  t T     `	`	 fp            hh( *FILE     3 file pointer

  u S +
    Output:

  t T     `	`	 Name          hh( Type      3 Description

  t T K
    `	`	 status        hh( *int      3 status
   `	`	  " hh( . 3 0 = failure
   `	`	  " hh( . 3 1 = okay
   `	`	  " hh( . 3 2 = start of record
   `	`	  " hh( . 3 6 = start of field

  u S     Returns:

  t T     `	`	 Name          hh( Type      3 Description

  t T     `	`	 bak123sfld()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S s External References:" stc123.h

  u T     Requirements:  Reading or writing a DR or any part of a DR within a file must
occur prior to backing up within the file.(#

  u T \ Processing: `	`	  X Function bak123sfld() backs up to the beginning of the last
  t T % subfield that was read or written for the file fp.  For a DDF
  t T  opened in 'write' mode, bak123sfld() deletes the current
subfield, sets the pointer to the previous subfield, and
  t T } returns the appropriate position in status.  For a DDF opened
in 'read' mode, the subfield pointer is changed to the
  t T 
  previous subfield read and the position is returned in status. 
  t T   A status of 'failure' is returned when attempting to back up
while positioned at the first subfield in a DDF.(#   !?        0*%%    t T               G       G    3# d p   @ >pQ Wm@# `(#(#V G      3.3.5 p    @`	`	 Check Functions(#`	

 p    @`	`	 The FIPS PUB 123 Function Library check functions query the DDR and
retrieve the format and description of the current record, field or
subfield, or next record, field, or subfield.  The check functions
may be used in application programs to assist in reading a DDF in an
unknown format or to generate reports.  These functions include:(#`	

  t T `	  p    @`	`	  X o X" chk123fld()ĩretrieves the format and description of the
current DR field(#

  t T   p    @`	`	  X o X" chk123nfld()ĩretrieves the format and description of
the next DR field to be processed(#

  t T h  p    @`	`	  X o X" chk123nrec()ĩretrieves the format and description of
the next DR to be processed(#

  t T   p    @`	`	  X o X" chk123nsfld()ĩretrieves the format and description of
the next subfield to be processed(#

  t T p  p    @`	`	  X o X" chk123rec()ĩretrieves the format and description of the
current DR(#

  t T   p    @`	`	  X o X" chk123sfld()ĩretrieves the format and description of
the current DR subfield.(#

 p    @`	`	 The check functions must be used at the level of read/write access. 
  t T  That is, if you are processing by record, use chk123rec or
  t T   chk123nrec; if you are processing by field, use chk123fld or
  t T ! chk123nfld; if you are processing by subfield, use chk123sfld or
  t T (# chk123nsfld.  The usage of these functions is described in the
following paragraphs.(#`	   T$@        0*%%    u T      G               K    0  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E chk123fldļ       Function Name:  chk123fld (#

  u T  Purpose: `	`	 To retrieve the description of the last DR field read or written. (#`	

  u T " Arguments: `	`	 chk123fld (*fp,*fdtag,*fdlen,**fdname,*fdcntrl,*fmts,*labs) (#`	

  u S     Input:

  t T C    `	`	 Name         hh( Type      3 Description

  t T     `	`	 fp           hh( *FILE     3 file pointer

  u S c	    Output:

  t T 
    `	`	 Name         hh( Type     3 Description

  t T     `	`	 fdtag[]      hh( *char     3 field tag 
  t T K
    `	`	 fdlen[]      hh( *char     3 field length 
  t T     `	`	 fdname[]     hh( **char    3 field name 
  t T     `	`	 fdcntrl[]    hh( *char     3 field controls 
  t T     `	`	 fmts[]       hh( *char     3 field format string 
  t T k    `	`	 labs[]       hh( *char     3 field labels 

  u S     Returns:

  t T     `	`	 Name         hh( Type      3 Description

  t T     `	`	 chk123fld()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S s External References:" stc123.h

  u T     Requirements:  Use chk123fld() after reading or writing a DR field and while
the DR is current; that is, before ending the DR with
  t T  end123rec() or before beginning another DR with beg123rec(). 
  t T \ The output character string fdname is dynamically allocated by
  t T $ chk123fld(); the application must release this variable prior
  t T  to a subsequent call to chk123fld().(#

  u T | Processing: `	`	  X Function chk123fld() returns the tag, length, name, field
controls, format, and labels of the last field read or written
  t T 
  for the current DR of file fp. (#   
 A        0*%%    u T      K                   3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E chk123nfldĽ  

    Function Name:  chk123nfld (#

  u T  Purpose: `	`	 To retrieve the description of the next DR field to be read or
written. (#`	

  u T  Arguments: `	`	 chk123nfld (*fp,*tag,*fdlen,**fdname,*fdcntrl,*fmts,*labs) (#`	

  u S {    Input:

  t T     `	`	 Name          hh( Type      3 Description

  t T     `	`	 fp            hh( *FILE     3 file pointer

  u S +
    Output:

  t T     `	`	 Name          hh( Type      3 Description

  t T K
    `	`	 tag[]         hh( *char     3 field tag
  t T     `	`	 fdlen[]       hh( *char     3 field length
  t T     `	`	 fdname[]      hh( **char    3 field name
  t T     `	`	 fdcntrl[]     hh( *char     3 field controls
  t T k    `	`	 fmts[]        hh( *char     3 field format string
  t T 3    `	`	 labs[]        hh( *char     3 field labels

  u S     Returns:

  t T S    `	`	 Name          hh( Type     3 Description

  t T     `	`	 chk123nfld()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S ; External References:" stc123.h

  u T     Requirements:  Use chk123nfld() after reading or writing a DR field.  After
  t T  writing a field, invoke chk123nfld() before ending the DR with
  t T \ end123rec() or beginning another DR with beg123rec().  If you
  t T $ invoke chk123nfld() after reading a field, the description of
the next field is retrieved, regardless of record boundaries. 
  t T  The output character string fdname is dynamically allocated by
  t T | chk123nfld(); the application program must release this
  t T D variable prior to a subsequent call to chk123nfld().(#

  u T   Processing: `	`	  X Function chk123nfld() returns the tag, length, name, field
controls, format, and labels of the next field to be read or
  t T e" the last DR field written to file fp. (#   e"B        0*%%    u T                        3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E chk123nrecĽ    Function Name:  chk123nrec (#

  u T  Purpose: `	`	 To retrieve the description of the next data record to be read or
the last data record written. (#`	

  u T  Arguments: `	`	 chk123nrec (*fp,*reclen,*leadid,*descr) (#`	

  u S {    Input:

  t T     `	`	 Name          hh( Type      3 Description

  t T     `	`	 fp            hh( *FILE     3 file pointer

  u S +
    Output:

  t T     `	`	 Name          hh( Type      3 Description

  t T K
    `	`	 reclen        hh( *long     3 record length
  t T     `	`	 leadid        hh( *char     3 leader identifier
  t T     `	`	 descr         hh( *char     3 description

  u S k    Returns:

  t T     `	`	 Name          hh( Type      3 Description

  t T     `	`	 chk123nrec()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S  External References:" stc123.h

  u T s    Requirements:  For a DDF opened in 'read' mode, use chk123nrec() to obtain
the format and description of the next record to be read.  For
  t T  a DDF opened in 'write' mode, use chk123nrec to return the
format and description of the last record written provided
that DR is current; that is, before ending the DR with
  t T \ end123rec() or before beginning another DR with beg123rec(). 
(#
  u T  Processing: `	`	  X Function chk123nrec() returns the length, leader identifier,
and description of the next DR to be read or the last DR
written.  The record description comprises the field
description for each field; delimited by the field terminator
(ASCII decimal 30).  Each field description comprises a field
tag, field control, name, labels, and format controls,
delimited by the unit terminator (ASCII decimal 31).(#
   e"C         0*%%    u T                    	   3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E chk123nsfldľ    Function Name:  chk123nsfld (#

  u T  Purpose: `	`	 To retrieve the description of the next DR subfield to be read or
written. (#`	

  u T  Arguments: `	`	 chk123nsfld (*fp,*tag,*descr,*frmt) (#`	

  u S {    Input:

  t T     `	`	 Name           hh( Type      3 Description

  t T     `	`	 fp             hh( *FILE     3 file pointer

  u S +
    Output:

  t T     `	`	 Name           hh( Type      3 Description

  t T K
    `	`	 tag[]          hh( *char     3 field tag
  t T     `	`	 descr[]        hh( *char     3 output description of subfield
  t T     `	`	 frmt[]         hh( *char     3 format

  u S k    Returns:

  t T     `	`	 Name           hh( Type      3 Description

  t T     `	`	 chk123nsfld()  hh( int        h3 success flag, returns 2 if end of
field or 1 if successful or 0 if
error(#

  u S  External References:" stc123.h

  u T ;    Requirements:  Use chk123nsfld() after reading or writing a DR subfield.
  t T  After writing a subfield, invoke chk123nsfld before ending the
  t T  DR with end123rec() or beginning another DR with beg123rec(). 
  t T  After reading a subfield, chk123nsfld() returns the next
subfield description, regardless of field or record
boundaries.(#

  u T  Processing: `	`	  X Function chk123nsfld() returns the field tag, description (in
the form of vector or Cartesian labels), and format of the
next DR subfield to be read or written.(#

 p    @`	`	  X If the subfield is part of an array descriptor, the
description returned is "NUMBER OF DIMENSIONS" with the format
"I" for the first subfield or the description "DIMENSION
LENGTH" with the format "I" for subsequent subfields prior to
the subfields containing data.(#   #D        0*%%  Ԍ p    @`	`	  X For files opened in write mode, if the next subfield does not
exist because the end of the field has been reached, the
description and format will be null and the return value of
  t T X chk123nslfd() is 2.(#


   `	`	   The description content depends upon the type of data
structure defined in the DDR for the next subfield.  For
  t T @ vector data structures, descr contains a single vector label;
  t T  for Cartesian data structures, descr contains a vector label
from each Cartesian label delimited by the character '!'.  No
  t T  label is placed in descr if the Cartesian label contains a
null vector label.  A leading '!' or adjacent '!'s within
  t T (
 descr represent a null vector label(s).(#
   
E         0*%%    u T      	                 3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E chk123recļ    Function Name:  chk123rec (#

  u T  Purpose: `	`	 To retrieve the description of the last data record read or
written.(#`	

  u T  Arguments: `	`	 chk123rec (*fp,*reclen,*leadid,*descr) (#`	

  u S {    Input:

  t T     `	`	 Name " hh( Type      3 Description

  t T     `	`	 fp           hh( *FILE     3 file pointer

  u S +
    Output:

  t T     `	`	 Name         hh( Type      3 Description

  t T K
    `	`	 reclen       hh( *long     3 record length
  t T     `	`	 leadid[]     hh( *char     3 leader identifier
  t T     `	`	 descr[]      hh( *char     3 description

  u S k    Returns:

  t T     `	`	 Name         hh( Type      3 Description

  t T     `	`	 chk123rec()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S  External References:" stc123.h

  u T s Requirements:  Use chk123rec() after reading or writing a data record and
while that DR is current; that is, before ending the DR with
  t T  end123rec() or before beginning another DR with beg123rec().
(#
  u T  Processing: `	`	  X Function chk123rec() returns the length, description, and
leader identifier of the last DR read or written.  The
record description comprises the field description for each
field, delimited by the field terminator (ASCII decimal 30). 
Each field description comprises the field tag, field
control, name, labels, and format controls, delimited by the
unit terminator (ASCII decimal 31). (#
   
 F         0*%%    u T                       3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E chk123sfldĽ     Function Name:  chk123sfld (#

  u T  Purpose: `	`	 To retrieve the description of the last DR subfield read or
written. (#`	

  u T  Arguments: `	`	 chk123sfld (*fp,*tag,*descr,*frmt) (#`	

  u S {    Input:

  t T     `	`	 Name          hh( Type      3 Description 

  t T     `	`	 fp            hh( *FILE     3 file pointer 
  t T c	    `	`	 tag[]         hh( *char     3 field tag

  u S 
    Output:

  t T     `	`	 Name          hh( Type      3 Description 

  t T     `	`	 descr[]      hh( *char     3 output label/description of subfield
  t T     `	`	 frmt[]        hh( *char     3 format 

  u S k    Returns:

  t T     `	`	 Name          hh( Type      3 Description 

  t T     `	`	 chk123sfld()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S  External References:" stc123.h

  u T s    Requirements:  Use chk123sfld() after reading or writing a DR subfield and
while the DR is current; that is, before ending the DR with
  u T  end123rec() or before beginning another DR with beg123rec().(#

  u T  Processing: `	`	  X Function chk123sfld() returns the description, in the form of
vector or Cartesian labels, and the format of the last DR
subfield read or written.(#

 p    @`	`	  X If the subfield is part of an array descriptor, the
description returned is "NUMBER OF DIMENSIONS" with the format
"I" for the first subfield or the description "DIMENSION
LENGTH" with the format "I" for subsequent subfields prior to
the subfields containing data.(#



   #G         0*%%  Ԍ   `	`	   The description content depends upon the type of data
structure defined in the DDR for the corresponding subfield. 
  t T  For vector data structures, descr contains a single vector
  t T X label; for Cartesian data structures, descr contains a vector
label from each Cartesian label delimited by the character
  t T  '!'.  No label is placed in descr if the Cartesian label
contains a null vector label.  A leading '!' or adjacent '!'s
  t T x within descr represent a null vector label(s).(#
   @H         0*%%    t T             G          3# d p   @ >pQ Wm@# `(#(#V G      3.3.6 p    @`	`	 Erase Functions(#`	

 p    @`	`	 The FIPS PUB 123 Function Library erase functions are used to erase
the DDR or the last DDR field or subfield written to a DDF opened in
'write' mode:(#`	

  t T   p    @`	`	  X o X" er123ddfld()ĩerases the last DDR field written(#
  t T 4  p    @`	`	  X o X" er123ddrec()ĩerases the DDR record(#
  t T `	  p    @`	`	  X o X" er123ddsfld()ĩerases the last DDR subfield written.(#

 p    @`	`	 The erase functions may be used only while processing the DDR; that
  t T  is, before the DDR is ended with end123ddrec().  If er123ddrec() is
  t T  called after end123ddrec(), the DDR and any subsequent DRs written
  t T < will be erased.  If er123ddfld() or er123ddsfld() is called after
  t T h end123ddrec(), subsequent errors may be encountered while processing
DRs. (#`	

 p    @`	`	 The following paragraphs describe the usage of these functions.(#`	


   pI         0*%%    u T                    !   0  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E er123ddfldĽ       Function Name:  er123ddfld (#

  u T  Purpose: `	`	 To erase the last field written to the data descriptive record.(#`	

  u T " Arguments: `	`	 er123ddfld (*fp,*status) (#`	

  u S     Input:

  t T C    `	`	 Name          hh( Type      3 Description

  t T     `	`	 fp            hh( *FILE     3 file pointer

  u S c	    Output:

  t T 
    `	`	 Name          hh( Type      3 Description

  t T     `	`	 status        hh( *int      3 status
   `	`	  " hh( . 3 0 = failure
   `	`	  " hh( . 3 2 = start of record
   `	`	  " hh( . 3 6 = start of field

  u S k    Returns:

  t T     `	`	 Name          hh( Type      3 Description

  t T     `	`	 er123ddfld()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S  External References:" stc123.h

  u T s    Requirements:  Function er123ddfld() may be invoked only for a DDF opened in
'write' mode during processing of the data descriptive record;
  u T  that is, prior to invoking function end123ddrec().(#

  u T  Processing: `	`	  X Function er123ddfld() erases the last DDR field written to
  t T ^ file fp.  The position of the DDR field is returned in status. 
  t T & A status of 'failure' is returned when attempting to erase a
DDR field that does not exist.(#
 
   ~J         0*%%    u T      !              ;%   3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E er123ddrecĽ    Function Name:  er123ddrec(#

  u T  Purpose: `	`	 To erase the entire data descriptive record.(#`	

  u T " Arguments: `	`	 er123ddrec (*fp,*status)(#`	

  u S     Input:

  t T C    `	`	 Name          hh( Type      3 Description

  t T     `	`	 fp            hh( *FILE     3 file pointer

  u S c	    Output:

  t T 
    `	`	 Name          hh( Type      3 Description

  t T     `	`	 status        hh( *int      3 status
   `	`	  " hh( . 3 0 = failure
   `	`	  " hh( . 3 2 = start of record

  u S     Returns:

  t T 3    `	`	 Name          hh( Type      3 Description

  t T     `	`	 er123ddrec()  hh( int        h3 success flag, returns 1 if
successful or 0 if error(#

  u S  External References:" stc123.h

  u T     Requirements:  Function er123ddrec() may be invoked only for a DDF opened in
'write' mode during processing of the data descriptive record;
  t T < that is, prior to invoking end123ddrec().  Invoking
  t T  er123ddrec() after ending data descriptive record processing
  t T  with end123ddrec() and beginning DR processing will cause all
DRs written to be lost.(#

  u T $ Processing: `	`	  X Function er123ddrec() erases the data descriptive record from
  t T  file fp and returns a  status of 'start of record'.(#   K        0*%%    u T      ;%              c)   3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E er123ddsfldľ    Function Name:  er123ddsfld (#

  u T  Purpose: `	`	 To erase a subfield of the data descriptive record.(#`	

  u T " Arguments: `	`	 er123ddsfld (*fp,*status) (#`	

  u S     Input:

  t T C    `	`	 Name           hh( Type     3 Description

  t T     `	`	 fp             hh( *FILE   3 file pointer

  u S c	    Output:

  t T 
    `	`	 Name           hh( Type     3 Description

  t T     `	`	 status         hh( *int     3 status
   `	`	  " hh( . 3 0 = failure
   `	`	  " hh( . 3 1 = okay
   `	`	  " hh( . 3 2 = start of record
   `	`	  " hh( . 3 5 = end of field
   `	`	  " hh( . 3 6 = start of field

  u S     Returns:

  t T     `	`	 Name           hh( Type     3 Description

  t T     `	`	 er123ddsfld()  hh( int       h3 success flag, returns 1 if
successful or 0 if error(#

  u S s External References:" stc123.h

  u T  Requirements:  Function er123ddsfld() may be invoked only for a DDF opened
in 'write' mode during processing of a data descriptive
  t T  record; that is, prior to invoking end123ddrec().(#

  u T $ Processing: `	`	  X Function er123ddsfld() erases the last DDR subfield written
  t T  to file fp.  The position of the erased DDR subfield is
  t T  returned in status.  A status of 'failure' is returned when
attempting to erase a DDR subfield that does not exist.(#
   EL         0*%%    t T      c)       G       -   3# d p   @ >pQ Wm@# `(#(#V G       3.3.7 p    @`	`	 Utility Functions(#`	

 p    @`	`	 Several utility functions have been provided with the FIPS PUB 123
Function Library to facilitate processing of binary (bit) data. 
These include:(#`	

  t T   p    @`	`	  X o X" g123order()ĩreturns the byte order of the current
operating architecture(#

  t T 
  p    @`	`	  X o X" l123tos()ĩconverts a long (full word) integer to a
character string as required for input to a FIPS PUB 123
write function, optionally reversing the order of the
bytes in the string(#

  t T h  p    @`	`	  X o X" s123tol()ĩconverts a character string to a long
integer, optionally reversing the order of the bytes  of
the string prior to converting.(#

 
A 6"x     J               d d 0                                                    N  x0** 0a #  d p   @ >pQ Wm@# 

  Figure 10
	 Binary Data Representation.
   S   #  X~ x    P 7qXP#  ppp  @  X 0x04030201 = unsigned 6730598510Ɛ

 ppp Big Endian:Ɛp
# i x    P 7AP# 
  } K K  ppp  @ High Order Byte > `	" Low Order ByteƐ
  } K   ppp  @ Most Significant Byte > `	" Least Significant ByteƐ
  } K   ppp  @ Byte #1 `	`	 Byte #2 " Byte #3 . Byte #4Ɛ
  } K   ppp  @ 0x04 X  X`	`	 0x03 X  X" 0x02 Xhh(  X. 0x01Ɛ
  } K k  ppp  @ 0000 0100 `	`	 0000 0011 " 0000 0010 . 0000 0001Ɛ


   S 	 # X~ x    P 7qXP#  ppp Little Endian:Ɛp
# i x    P 7AP# 
  } K t  ppp  @ Low Order Byte > `	" High Order ByteƐ
  } K <  ppp  @ Least Significant Byte > `	" Most Significant ByteƐ
  } K 
  ppp  @ Byte #1 `	`	 Byte #2 " Byte #3 . Byte #4Ɛ
  } K 
  ppp  @ 0x01 X  X`	`	 0x02 X  X" 0x03 Xhh(  X. 0x04Ɛ
  } K   ppp  @ 0000 0001 `	`	 0000 0010 " 0000 0011 . 0000 0100Ɛ


   S  # X~ x    P 7qXP#  ppp Middle Endian (left to right):Ɛp
# i x    P 7AP# 
  } K   ppp  @ ©> Low Order Byte  `	" High Order Byte > Ɛ
  } K e  ppp  @ ©> Least Sig. Byte  `	" Most Sig. Byte  >Ɛ
  } K -  ppp  @ Byte #1 `	`	 Byte #2 " Byte #3 . Byte #4Ɛ
  } K   ppp  @ 0x02 X  X`	`	 0x01 X  X" 0x04 Xhh(  X. 0x03Ɛ
  } K   ppp  @ 0000 0010 `	`	 0000 0001 " 0000 0100 . 0000 0011Ɛ
  } K   ppp  @ 16 bit big endian   X" 16 bit big endianƐ
 ppp  @ ©32 bit little endianƐ

   S  # X~ x    P 7qXP#  ppp Middle Endian (right to left):Ɛp
# i x    P 7AP# 
  } K   ppp  @ < High Order Byte  `	" Low Order Byte  < Ɛ
  } K V  ppp  @ < Most Sig. Byte  `	" Least Sig. Byte   <Ɛ
  } K   ppp  @ Byte #1 `	`	 Byte #2 " Byte #3 . Byte #4Ɛ
  } K   ppp  @ 0x03 X  X`	`	 0x04 X  X" 0x01 Xhh(  X. 0x02Ɛ
  } K   ppp  @ 0000 0011 `	`	 0000 0100 " 0000 0001 . 0000 0010Ɛ
  } K v  ppp  @ 16 bit little endian   X" 16 bit little endianƐ
 ppp  @ ©32 bit big endianƐ

  p    @`	`	 Binary data are stored as big endian, little endian, or middle
  t T D endian.  These methods are depicted in figure 9.  Use g123order() to
determine the architecture of the your processing computer; if the
architecture is different than that of the DDF to be read/written,
  t T  use the reverse parameter when calling s123tol() or l123tos() to
  t T  reverse the order of the bytes.1  (#`	





  t T ! 1 p   The Spatial Data Transfer Standard (FIPS PUB 173) specifies that all
binary data be represented in big endian format.(# 
 0  T$M         0*%% '#O-  AN 0  $  (#(#  (#(#  A'#$  0    N         0*%% '#O-  AN 0    u T      -              2   0  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E g123orderļ       Function Name:  g123order(#

  t T  Purpose:`	`	 To return the byte order of the current machine.

  t T ! Arguments:`	`	 g123order (*order)

  u T     Input: none

  u S B    Output:

   `	`	 Name          Type      Description

  t T b	    `	`	 order         *int      byte order            
   `	`	  " hh( . 0 = little endian 
   `	`	  " hh( . (least significant byte first)
   `	`	  " hh( . 1 = big endian
   `	`	  " hh( . (most significant byte first)
   `	`	  " hh( . 2 = middle endian

  u S     Returns:

   `	`	 Name          Type      Description

  t T     `	`	 g123order()   int       success flag returns 1

  u T  External References: `	" none(#

  u T     Requirements:  Based on the value of order returned by g123order, determine
  t T  whether subsequent calls to l123tos or s123tol will require
byte reversal. (#

  u T < Processing `	`	  X Function g123order() places a long integer test value into
memory and returns the byte ordering of the current machine.(#


   ]O         0*%%    u T      2              g5   3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E l123tosĺ    Function Name:  l123tos(#

  t T  Purpose: `	`	 To convert a long integer to a 4byte character string and change
its byte ordering when specified.(#`	

  t T  Arguments:`	`	 l123tos (num,*string,reverse)

  u S y    Input:

   `	`	 Name          Type     Description

  t T     `	`	 num           long     number to be converted
  t T a	    `	`	 reverse       int      reverse byte order flag
   `	`	  " hh( . 1 = reverse
   `	`	  " hh( . 0 = do not reverse

  u S     Output:

   `	`	 Name          Type     Description

  t T     `	`	 string[]      *char    4byte character string

  u S 1    Returns:

   `	`	 Name          Type     Description

  t T Q    `	`	 l123tos()     int      success flag returns 1


  u T  External References:  `	" none(#

  u T :    Requirements:  Declare the output character string to be 4 bytes long. 
Specify whether byte order reversal is required based on a
  t T  prior call to g123order.(#

  u T [ Processing: `	`	  X Function l123tos() moves a long integer value to a 4byte
  t T $ string variable.  Function l123tos() will also change the byte
order of the long integer from Most Significant Byte First
(big endian) to Least Significant Byte First (little endian)
  t T | and vice versa as specified by reverse.(#
   DP         0*%%    u T      g5              9   3  t T    # d p   @ >pQ Wm@#    `	`	  " hh( . 3 pp9 ?   E s123tolĺ    Function Name:  s123tol(#

  u T  Purpose: `	`	 To convert a 4byte character string to a long integer and change
its byte ordering when specified.(#`	

  u T  Arguments: `	`	 s123tol (*string,*num,reverse)(#`	

  u S {    Input:

  t T     `	`	 Name          Type    . Description

  t T     `	`	 string[]      *char   . character string
  t T c	  p   `	`	 reverse       int     . reverse byte order flag(# 
 p    @`	`	  X  X"  Xhh(  X. 1 = reverse(#
    `	`	  X  X"  Xhh(  X. 0 = do not reverse(#

  u S     Output:

  t T     `	`	 Name          Type    . Description

  t T     `	`	 num           *long   . converted number 

  u S 3    Returns:

  t T     `	`	 Name          Type    . Description

  t T S    `	`	 s123tol()     int     . success flag returns 1


  u T  External References: `	" none(#

  u T <    Requirements:  Declare the input string to be 4 bytes long.  Specify the
  t T  value of reverse based on a prior call to g123order.(#

  u T  Processing: `	`	  X Function s123tol() reverses the order of the bytes, if
  t T ^ specified by reverse,and moves the 4byte character string to
a long integer variable.(#
   Q         0*%%    t T      4            4.   `	`	 MANAGEMENT OF PROGRAM

  t T X 4.1   `	`	 POINT OF CONTACT

   `	`	 Standards Section
   `	`	 Branch of Standards and Technology
   `	`	 Office of Research
   `	`	 U.S. Geological Survey
   `	`	 526 National Center
   `	`	 Reston, VA  22092

  t T  4.2   `	`	 SOFTWARE CHANGE NOTICE

   `	`	 Configuration Management Office
   `	`	 National Mapping Division
   `	`	 U.S. Geological Survey
   `	`	 510 National Center
   `	`	 Reston, VA  22092

