WPCgH 2BV[Z #|h2cpi (M)LtTddd,wldp@~rQ@HP LaserJet IIIDHPLASIII.PRSdp@~rQ,\,y@#|h2 ZM vHP LaserJet IIIHPLASIII.PRSx  @,\,yX@a8DocumentgDocument Style StyleXX` `  ` 2<pQkk,a4DocumentgDocument Style Style . a6DocumentgDocument Style Style GX  a5DocumentgDocument Style Style }X(# a2DocumentgDocument Style Style<o   ?  A.  2vntX a7DocumentgDocument Style StyleyXX` ` (#` BibliogrphyBibliography:X (# a1Right ParRight-Aligned Paragraph Numbers:`S@ I.  X(# a2Right ParRight-Aligned Paragraph Numbers C @` A. ` ` (#` 2  n  a3DocumentgDocument Style Style B b  ?  1.  a3Right ParRight-Aligned Paragraph Numbers L! ` ` @P 1. ` `  (# a4Right ParRight-Aligned Paragraph Numbers Uj` `  @ a. ` (# a5Right ParRight-Aligned Paragraph Numbers _o` `  @h(1)  hh#(#h 2   X 1 a6Right ParRight-Aligned Paragraph Numbersh` `  hh#@$(a) hh#((# a7Right ParRight-Aligned Paragraph NumberspfJ` `  hh#(@*i) (h-(# a8Right ParRight-Aligned Paragraph NumbersyW"3!` `  hh#(-@p/a) -pp2(#p a1DocumentgDocument Style StyleXqq   l ^) I. ׃  2h+/ ZZDoc InitInitialize Document Style  0*0*  I. A. 1. a.(1)(a) i) a) I. 1. A. a.(1)(a) i) a)DocumentgTech InitInitialize Technical Style. k I. A. 1. a.(1)(a) i) a) 1 .1 .1 .1 .1 .1 .1 .1 Technicala5TechnicalTechnical Document Style)WD (1) . a6TechnicalTechnical Document Style)D (a) . 2WHa2TechnicalTechnical Document Style<6  ?  A.   a3TechnicalTechnical Document Style9Wg  2  1.   a4TechnicalTechnical Document Style8bv{ 2  a.   a1TechnicalTechnical Document StyleF!<  ?  I.   2oa7TechnicalTechnical Document Style(@D i) . a8TechnicalTechnical Document Style(D a) . PleadingHeader for numbered pleading paperP@n   $] X X` hp x (#%'0*,.8135@8:Q9`MeH% YCcEyJ`JT9eM`MOHOO;T>[Hm^`@j[ceJ>M MHHeHJe[[,,TTTTTTTJJJJJJJJJJJJJJJJJJJ>>>>>>>MMMMMMMMMMMMMMMMMMMM MMMMMMMHHHHHHHHHHHHeeeeeeeeeeeeeeeeeeee,McM`%e[cC;,"m'^,,ETTe,,,T,,,,TTTTTTTTTT,,EcT^`MJc`%JYHy`eOhVVT```[Q,,,CC,HMHMH1MM H tMMMM/C1MJtJJ@CCC,TTTTT,,,,TTTTTTCTQ cHcHcHcHcHr^HMHMHMHMH% % % % `MeMeMeMeM`M`M`M`M[JcH`MeMeM[J`MOMcHcHcH^H^H^H^H`MMHMHMHMHcMcMcMcMcMcM`M`M% % % % o@JYHH 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```CTT,EJJTTT66T44CCT4,,CCT11TTRReCC`C[{{QQK,CC4"``C`J``C充C,,`Q``````````x,CcTOTmc@,T`JTM`h[``````````C``````tYQh`9O```````C```````C````C```````````````````````````````````````````,```,```,```,`````````````cMTOJCcMMCQ>`MeQ%#YCcCyO`J`@eMmQOMQV>T>[O{``J{`mhMCM##MOOhMVh[`,,TTTTTTTMMMMMMMMMMMMMMMMMMMCCCCCCCMMMMMMMMMMMMMMMMMMMM############MMMMMMMOOOOOOOOOOOOhhhhhhhhhhhhhhhhhhhh,QcM`%e[mC;,?xxx,wx6X@8;X@tTddd,Wmdp@>pQ@LtTddd,'wldp@~rQ@uSddd,@dp,`QtTddd,^dphQQHH<!,~ ,< P7,Pld!T,,,QTxP7Pmd!T,,,xTp?7>tTddd,Vdp@h'@nQq,lFxP7FP^u&,~x&xP7xPZ[XPSQRWUf t@2& ubf u~3b te! !5e!mo%:ںt!lbF u l&l2 4 2, 4 f5 R>"D,( 0 ^VM=EME},EV ^$$EEE4lll7lMMMMM=}l}l}l}lEVVVVEEEE4MEVV4E MMM====EMMMMMMEE}l}l}l}lm,llllEE4EEVV$$$$$$$EEEEEE4ElE$$44EVE/NEEEVE4"EEEEEE EEEEEEEEEExMEMEE^$EEEEEEEEEEEEEEEEw,^E EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEMMEV}l,MEVE   4o=Ef4MVllVV44llllllllllllVVVVVVVVVVVVVVVVVVVVME}V4M"D,( 0 ^&&b&&&&&&&&&&&Z&HQ ZQ7Qbk..&QQQ@    ppp     9&&&&&&&&&&&&pZZZZZH    ppppQ b b b b Q Q Q Q @ZQ b b @Q  ZZZHHHHQ     Z Z Z Z Z Z Q Q ppppz7ppppQ Q@Q Q b b .......&&&Q Q Q Q Q Q @Q pQ ..&@@Q b Q /NQQQ&&&&&&&&&&bQ@"QQQQQQQQQQQQQQQQxZ&&QZ&Q& Qk.QQQQQQQQQQQQQQQQ7kQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQZ&Z Q bp7ZQ&b Q &@|HQt@Zb pp bb@@&&&&&&&                    pppppppppppp       bbbbbbbbbbbbbbbbbbbb Z Qb@Z (#.4UUUUUUUUUUUUUY5D9$ %#}|2PkCLlP#User-Specified Data uP $User-Specified DataX4Cz?#e $#}|2PkCLlP#Models and Formats uP #Models and Formats& ]f]f ]  2w2  U  2  2 J J2Q-<t #}|2PkCLlP#TRANSLATORS uP  hTRANSLATORSG#2]#}|2PkCLlP#A uP AG#2u#}|2PkCLlP#B uP BG#2#}|2PkCLlP#C uP CG#2#}|2PkCLlP#D uP  DR.=l#}|2PkCLlP#SDTS PROFILE uP  -SDTS PROFILEc?NK#}|2PkCLlP#FIPS PUB 123 FUNCTION LIBRARY uP #{FIPS PUB 123 FUNCTION LIBRARY& Mh /lA /_A `ehh pW9B` #}|2PkCLlP#SDTS FIPS PUB123 & uP  SDTS FIPS PUB123 T6?` j#}|2PkCLlP#Transfer Files& uP  ^Transfer Files Q&h 3&E# 3&E# i#hhG)2#%#}|2PkCLlP#C& uP $C # lR&h q4&F# d4&F# j#hhG)2$%#}|2PkCLlP#A& uP $A # R&h 4&F# ~4&F# j#hhG)2#%#}|2PkCLlP#B& uP $B # R&h  4&tF# 4&gF# hj#hhG)2#d%#}|2PkCLlP#D& uP k$D }#}  tT #dp@>pQWm@#}X+#dp@>pQWm@#Programmers Reference Manual for FIPS PUB 123 Function Library }߉ tT 3/93` `  "hh(.3pp9?  ExxK P X` hp x (#%'0*,.8135@8: :install (# ` ` or(#`  uT ` ` X <drive> :load123 <f123dir>(#  tT ` ` where <drive> contains the FIPS PUB 123 diskette, and <f123dir> is the root directory into which the software is to be installed. The  uTF  install program is an aid to invoking the load123 program. Install will prompt for and create the directory structure into which the  uT software is to be installed before invoking the load123 program.  uT The load123 program may be invoked to extract and copy the software into the following subdirectories within the current directory or  tT% the directory specified by <f123dir>:(#`  tT} ` ` Directory"Xhh(X.Description(#  uT ` `  \ <f123dir> \f123app ` .FIPS PUB 123 sample application programs (#  uT ` `  \ <f123dir> \f123bat ` .FIPS PUB 123 .bat files to create the Function Library(#  uT/# ` `   \ <f123dir> \f123doc ` .Introductory documentation (readme.123) and FIPS PUB 123 Programmers Reference Manual(#\$ 0*%%Ԍ uT ` `   \ <f123dir> \f123inc ` .Include ( .h ) files used by FIPS PUB 123 functions(#  uTY ` `  \ <f123dir> \f123lib ` .FIPS PUB 123 Function Library (#  uT ` `   \ <f123dir> \f123lst ` .Compiled source code listings for FIPS PUB 123 functions(#  uT ` `   \ <f123dir> \f123obj ` .Object code for FIPS PUB 123 functions(#  uT  ` `   \ <f123dir> \f123src ` .Source code for FIPS PUB 123 functions(#  uT9 ` `   \ <f123dir> \f123utl ` .FIPS PUB 123 utility programs(#  uTf ` `  \ <f123dir> \samdlg3 ` .U.S. Geological Survey Digital Line Graph Level 3 data files in SDTS format (DLG3/SDTS)(#  uT ` `  \ <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.(#`  tT 2.1.2` ` Creating the FIPS PUB 123 Function Library(#`  uT ` ` Prior to compiling, edit the include file stc123.h to ensure that  uT" the constant MSDOS is defined as 1 (one) and all other operating  tT2# system compilation constants are defined as 0 (zero) (see figure 2).  uT^$ Use the f123comp.bat file to compile each routine in^$ 0*%%  uT  \ <f123dir> \f123src\ and generate the object code in directory  uT-  \ <f123dir> \f123obj\ . The following compile options are used to compile the source code using Microsoft C version 5.1:(#`  uT  ` `  cl /Os /AL /c /Fs ..\f123lst\ /W3 /I ..\f123inc\ /Fo ..\f123obj\  uT  (#(#(#(#` `  X" ..\f123src\ <source> .c (# A xK ddZs x *Zs  tT #dp@>pQWm@#H  Figure 2  uT x The stc123.h File Specifies the MSDOS Platform.#dp@>pQWm@# /************************************************************************* * 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 (#(#0A'#$ ` ` where:  tTD ` `  oX"/Osĩoptimizes for size reduction(#  tT! ` ` X oX"/ALĩuses the large memory model(#  tT# ` ` X oX"/cĩperforms a compile and produces object code(#0# 0*%%'#!A 0Ԍ tT ԙ` ` X oX"/Fsĩproduces a source listing file placed in  uT,  \ <f123dir> \f123lst\ (#  tT ` `  oX"/W3ĩdisplays level 3 warnings(#  tT ` `  oX"/Iĩspecifies that compile should also search directory  uT   \ <f123dir> \f123inc\ for include files(#  uTb ` `  oX"/Fo ĩspecifies that the object files (* .obj ) are to be  uT placed in directory \ <f123dir> \f123obj\ (#  uT ` `  oX"<source> .c ĩC source code file located in directory  uT  \ <f123dir> \f123src\ .(# ` ` If the Microsoft CodeView debugger is to be used, replace option  tT /Os with the options /Zi and /Od. The /Zi option creates object  tT code for use with CodeView and the /Od option disables code  uT optimization. Note: the object code produced with these options will be larger.(#` ` ` Create a run-time library after obtaining the object code for each  uT routine. Microsoft C provides the library manager LIB to create, organize, and maintain run-time libraries. A response file  uT  f123lib.rsp is included for input to the library manager to generate the library (see figure 3). (#` Aa hxKz hddZsxh*Zs ?  #dp@>pQWm@# H  Figure 3  uT FIPS PUB 123 MSDOS Library Response File ( f123lib.rsp ).#dp@>pQWm@#  ..\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&  tT  + ret_dv + ret_fv + ret_matc hhh(+ 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:(#`  tT ` ` X oX"Line 1the name of the library(# 0]$ 0*%%'#a0Ԍ$(#(#(#(#Pa'#$ԙ  tT| ` ` X oX"Line 2the character "y" indicating the named library is to be created if it does not exist(#  tT ` ` X oX"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(#  tT ` ` X oX"Line n+1the name of the cross-reference listing to be created.(#  0$0*%%'#a0Ԍ` ` Invoke the Microsoft C library manager by using the command(#`  uTX ` `   lib @f123lib.rsp ` ` (#`  uT ` ` The response file f123lib.rsp creates the library fips123.lib and  uT 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.(#`  tT 2.1.3` ` Creating an Executable Application (#` ` ` Prior to compiling the application program(s), 'include' the FIPS  uT 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(#`  uT ` `   link /co <app_pgm> ` ` where:(#`  tT ` `  o` "/coĩprepares the executable for debugging. This option  tT may be used only if the /Zi and /Od options were used when the application program was compiled(# Y$0*%%Ԍ tT ` ` X oX"<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:(#`  uT` ` ` X  \ <f123dir> \f123lib\fips123.lib (# ` ` or another library to which the FIPS PUB 123 Function Library was copied.(#`  tT= ` ` 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. (#`  tT 2.2` ` UNIX  tTE 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  uT 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:(#`  uT! ` ` X  cd <f123dir>(#  uT+# ` ` X  tar xv <#> ; install (# X$0*%%Ԍ` ` where:(#`  tTX ` `  o` "<f123dir> specifies the root directory into which the software is to be installed(#  uT ` ` X oX" éxv are the tar arguments for file extraction and verbose(#  tTa ` ` X oX"<#> is a digit 09 corresponding to the diskette or tape cassette/cartridge device. For example, if the device  tT is /dev/rmt/0, then <#> is 0. (#  uT= ` ` The UNIX tape archival utility ( tar ) copies the software into the following directories:(#`  tT ` `  Directoryhh(X.X3Description(#  uT ` `  <f123dir> /f123app ` .X3FIPS PUB 123 sample application programs (#  uTs ` `  <f123dir> /f123bat .X3FIPS PUB 123 .bat files to create the FIPS PUB 123 Function Library(#  uT ` `  <f123dir> /f123doc .X3Introductory documentation  uT  (readme.123) and the Programmers Reference Manual for FIPS PUB 123 Function Library (#  uT~ ` `  <f123dir> /f123inc .X3Include ( .h ) files used by FIPS PUB 123 functions(#  uT ` `  <f123dir> /f123lib .X3FIPS PUB 123 Function Library (#  uT" ` `  <f123dir> /f123lst .X3Compiled source code listings for FIPS PUB 123 functions(# ]$0*%%Ԍ uT ` `  <f123dir> /f123obj .X3Object code for FIPS PUB 123 functions(#  uTY ` `  <f123dir> /f123src .X3Source code for FIPS PUB 123 functions(#  uT ` `  <f123dir> /f123utl. X3FIPS PUB 123 Function Library utility programs(#  uT  ` `  <f123dir> /samdlg3 .X3U.S. Geological Survey Digital Line Graph level 3 data files in SDTS format (DLG3/SDTS)(#  uT ` `  <f123dir> /samtiger ` 3U.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.(#`  tT% 2.2.2` ` Creating the FIPS PUB 123 Function Library(#`  uT} ` ` Prior to compiling, edit the include file stc123.h to ensure that  tT  the appropriate UNIX constant is defined as 1 (one) and that all other operating system compilation constants are set to 0 (zero).  uT" (This constant is currently defined only for the Data General ( DG )  uT/# UNIX platform as shown in figure 4.) Use the f123comp.m 'make' file  uT\$ to compile each routine in <f123dir> /f123src/ and generate the\$0*%%  uT 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):(#`  uT ` ` X  gcc éc éWall éansi épedantic éI ../f123inc  uT  ../f123src/ < source >.c (#  xK ddZsx *Zs  tT #dp@>pQWm@#H  Figure 4  uT  The stc123.h File Specifies the UNIX Platform.#dp@>pQWm@# /************************************************************************* * 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'#$  tT ` ` whereX :(#  tT ` `  o` "écĩperforms a compile and produces object code(#  tTC ` ` X oX"éWallĩprints extra warning messages(#  tT! ` ` X oX"éansiĩsupports all ANSI standard C features; turns off certain features of GNU C that are incompatible with ANSI C(#0#0*%%'# 0Ԍ tT ԙ` ` X oX"épedanticĩissues all warnings demanded by strict ANSI standard C(#  tT ` ` X oX"éIĩspecifies the compiler should also search  uT <f123dir> /f123inc for include files.(#  uT  ` ` 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  tTb that the object code produced with the ég option will be larger.(#` ` ` Create a run-time library after obtaining the object code for each  uT routine. UNIX provides the archive and library maintainer ar to create and update library files to be used by the link editor. The  uT? shell script f123lib.m is included to generate the library. The shell script contains the command: (#`  uT ` ` X  ar éruv ../f123lib/fips123.a ../f123obj/*.o (# ` ` where:(#`  tTu ` ` X oX"rĩreplaces files in archive(#  tT ` ` X oX"uĩadds only new or updated files(#  tT% ` ` X oX"vĩprovides a verbose listing of archive actions(#  uT} ` ` X oX" ../f123lib/fips123.a ĩspecifies the library name(#  uT ` ` X o X"../f123obj/*.o ĩindicates a wildcard file specification  uT" representing a list of files with ' .o ' extensions that are to be included in the library.(# \$0*%%Ԍ uT ` ` Invoke f123lib.m as a standard UNIX shell script to build the  uT- 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.(#`  tT 2.2.3` ` Creating an Executable Application (#` ` ` Prior to compiling the application program(s), 'include' the FIPS  uT 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  uT Function Library modify one of the sample makefiles sam_prg2.mak ,  uT  samprg2b.mak , sam_prg3.mak , or samprg3b.mak (see figure 5) to reflect the correct: (#`  !VxK<6dd` *#dp@>pQWm@# H  Figure 5  uT Sample Link Makefile ( sam_prg2.mak ).#dp@>pQWm@#  uT  CC = gcc ég -Wall -ansi -pedantic -I ../f123inc Ɛ  uTY  PGMNAME= ../f123app/sam_prg2 Ɛ  uT  SOURCE= ../f123app/sam_prg2.c Ɛ  uT{  OBJECTS= ../f123obj/sam_prg2.o Ɛ  uT   LIB= ../f123lib/fips123.a Ɛ  all: setup $(PGMNAME)Ɛ  setup:Ɛ  $(OBJECTS): $(SOURCE)Ɛ  uT  Xcd ../f123obj ; $(CC) -c $(SOURCE)Ɛ  $(PGMNAME): $(OBJECTS)Ɛ  tT  X$(CC) $(OBJECTS) $(LIB) -o $(PGMNAME)Ɛ   tTI ` ` X oX"Options to compile the application program(#  tTu ` ` X oX"Program name(#  tT ` ` X oX"Name of the object module(#  tT ` ` X oX"Name of the library with which to link.(#  uT% ` ` Invoke the make utility to create the executable using the following command:(#` ` `   uT ` `   make éf < app_pgm >.mak 0[$0*%%'#p0Ԍ$(#(#(#(#'#$ԙ  tTD ` ` whereX :(#  uT ` `  o` "éf indicates that the file < app_pgm >.mak contains the  uT instructions for the make command(#  uT" ` ` X oX" < 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 to0W$0*%%'#p0 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. (#`  tT 2.3` ` MVS(#` ` ` To be provided at a later date.  tT 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,  uT having the same hardware and compiler. The library file ( fips123.a  uT or fips123.lib ) and all FIPS PUB 123 data files (*.ddf) must be  uT transferred as type binary ; all other files may be transferred as  uTG type ascii . Consult Using TCP/IP on the DG/UX System or your site network administrator for additional information concerning FTP.(#` 0*%%  tT 3.` ` SOFTWARE FUNCTIONS  tTX 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. (#` L0*%% .Table 1 !File/Data Manipulation Functions ` `    ` ` X Function Purpose(# ` `     tT ` `   bak123fld()hh( .Backs up to the beginning of the last DR field read or written(# ` `    tT` ` `   bak123rec()hh( .Backs up to the beginning of the last DR read or written(# ` `   tT ` `   bak123sfld() .Backs up to the beginning of the last DR subfield read or written(#  tT ` `   beg123ddrec() .Initializes a DDR for the input or output file(#  tTh ` `   beg123file() .Opens an input or output file for processing(#  tT ` `   beg123rec()hh( .Initializes a DR for the input or output file(#  tT ` `   chk123fld()hh( .Retrieves a description of the last DR field read or written(#  tTp ` `   chk123nfld() .Retrieves a description of the next DR field to be read or the last one written(#  tT ` `   chk123nrec() .Retrieves a description of the next DR to be read or the last one written(#  tT  ` `   chk123nsfld() .Retrieves a description of the next DR subfield to be read or written(# ` `   tTx ` `   chk123rec()hh( .Retrieves a description of the last DR read or written(# ` `    0*%% h(Table 1Continued !File/Data Manipulation Functions ` `    ` ` X Function Purpose(# ` `     tT ` `   chk123sfld() .Retrieves a description of the last DR subfield read or written(#  tT` ` `   end123ddrec() .Terminates DDR processing(#  tT ` `   end123file() .Closes an input or output file  tT ` `   end123rec()hh( .Terminates the processing of a DR(#  tT ` `   er123ddfld() .Erases the last DDR field written  tT ` `   er123ddrec() .Erases the entire DDR written(#  tT0 ` `   er123ddsfld() .Erases the last DDR subfield written  tT ` ` X  g123order() hh(X.Returns the byte order of the current machine (big, little, or middle endian)(#  tT ` ` X  l123tos() hh(X.Converts a long integer to a character string(#  tTp ` `   rd123ddfld() .Reads the next DDR field  tT ` `   rd123ddrec() .Reads the entire DDR  tT ` `   rd123ddsfld() .Reads the next DDR subfield  tT  ` `   rd123fld()hh( .Reads the next DR field(#  tT ` `   rd123rec()hh( .Reads the next DR(#  tT@ ` `   rd123sfld()hh( .Reads the next DR subfield(#  tT ` ` X  s123tol() hh(X.Converts a character string to a long integer(# ` `   (#0*%% h(Table 1Continued !File/Data Manipulation Functions ` `    ` ` X Function Purpose(# ` `     tT ` `   wr123ddfld() .Writes a DDR field  tT ` `   wr123ddrec() .Writes the DDR  tT( ` `   wr123ddsfld() .Writes a DDR subfield  tT ` `   wr123fld()hh( .Writes a DR field(#  tTH ` `   wr123rec()hh( .Writes a complete DR(#  tT ` `   wr123sfld()hh( .Writes a DR subfield(# ` `   ` `  "  $0*%% 6"|J<dd%*#dp@>pQWm@# F  Figure 6 Sample Function Calling Sequence for a Write Application. #TxP7QP# X` hp x (#%'0*,.8135@8:pQWm@# H  Figure 7 Sample Function Calling Sequence for a Read Application. #TxP7QP#  dBJ  INVOKE beg123file() TO OPEN FIPS PUB 123 FORMAT FILE FOR READING (INPUT) OPEN USERSPECIFIED DATA MODEL AND FORMAT FILE FOR WRITING (OUTPUT)  dB<  * INVOKE beg123ddrec() TO INITIALIZE FIPS PUB 123 DATA DESCRIPTIVE RECORD WHILE NOT END OF DATA DESCRIPTIVE RECORD DO  dB.  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  dB  * INVOKE beg123rec() TO INITIALIZE FIPS PUB 123 INPUT DATA RECORD  WHILE NOT END OF RECORD DO  dB  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  dB  * INVOKE end123rec() TO END PROCESSING OF CURRENT FIPS PUB 123 DATA RECORD ENDWHILE  dB  INVOKE end123file() TO CLOSE FIPS PUB 123 INPUT FILE CLOSE USER-SPECIFIED FORMAT OUTPUT FILE &$(#(#(#(#$'#$0$0*%%'#+0  tT 3.2` ` STANDARDS AND CONVENTIONS  tTX 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. (#`  tTh 3.2.2` ` Usage ` ` The function types and macros of the FIPS PUB 123 Function Library  uT are declared in the header files stc123.h and gvd123.h. The header  uT file stc123.h should be included in the main application program and in any subroutine that calls a FIPS PUB 123 function.(#`  uT ` ` 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  uTX status indicators or accept a file option. The valid status and  uT  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  tT> 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.(#`  tT ` ` 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*%% xJxddZsTEMP.2 x*Zs{#dp@>pQWm@# H  Figure 8 L Compressed FixedLength Bit Data Within a Data Record. #dp@h'V@# Characters Bits Bits  Bits  Digits ab 101 01 11111 1111 12  Qx #FxP7 lFP# ...,A(2),B(3),B(2)B(8),I(2),...  tT[ # dp@h'V@# 3 3 3 3 3                         31 3 131 11 11 3 1 31 3 13 0110 0001 0110 0010 1010 1111 1111 1000 0011 0001 0011 0010      1 Zero Fill $(#(#(#(#'#$  tT  ` ` The field and subfield level read functions ( rd123fld() and  tT8  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.(#`  tT@ ` ` 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  tT# subfield write functions ( wr123fld() and  wr123sfld() ) require a(#` 0# 0*%%'# 0 !x<ddZs!x*JZsi#dp@~rQwl@# H  Figure 9 Uncompressed FixedLength Bit Data.  tT #dp@h'V@# Characters Bits Bits  Bits  Digits ab 101 01 1111 1111 12  ^ #x&xP7 ~xP# ..,A(2),B(3),B(2),B(8),I(2),...  tT # dp@h'V@# 3 3 3 3 3                        31 1 1 1 11 1 1 1 1 0110 000130110 001031010 000030100 000031111 111130011 000130011 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  tT 3.3` ` FUNCTION DESCRIPTIONS ` ` This section provides a concise description of each FIPS PUB 123 function organized by usage as follows:(#`  tT ` ` X oX"Begin/End functionsinitialize and terminate file, DDR, and DR processing(#  tT` ` ` X oX"Read functionsread DDR and DR on record, field, and subfield level(#  tT ` ` X oX"Write functionswrite DDR and DR on record, field, and subfield level(#  tTh ` ` X oX"Backup functionsback up the currency pointers for the DR record on a record, field, or subfield level(#  tT ` ` X oX"Check functionsretrieve the DDR description of a record, field, or subfield(#  tTp ` ` X oX"Erase functionserase the last DDR record, field, or subfield written(#  tT ` ` X oX"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*%%Ԍ tT 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:(#`  tT4 ` ` X oX" beg123ddrec() ĩinitiates DDR processing(#  tT` ` ` X oX" beg123file() ĩinitiates processing of a DDF(#  tT ` ` X oX" beg123rec() ĩinitiates processing of a DR (#  tT ` ` X oX" end123ddrec() ĩterminates DDR processing (#  tT ` ` X oX" end123file() ĩterminates processing of the DDF (#  tT ` ` X oX" end123rec() ĩterminates processing of a DR.(#  tTh ` ` Use of the functions  beg123file()  and  end123file()  is mandatory for  tT all DDFs whether opened in 'read' or 'write' mode.  end123ddrec()   tT and  end123rec()  are required for files opened in 'write' mode;  tT however  end123rec()  is     optional when immediately followed by a call  tT to  end123file() . (#` D#0*%%  uT ~Zs tT #dp@>pQWm@#` `  "hh(.3pp9?  E beg123ddrec  X` hp x (#%'0*,.8135@8: for file pointer fp from memory.(# $0*%%  uT ~U3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E beg123file   Function Name:   beg123file(#  uT  Purpose: ` ` To open a FIPS PUB 123 data descriptive file for reading or writing. (#`  uT  Arguments: ` `  beg123file (*f_name,mode,*int_level,*ice,*ccs,**fp)(#`  uS{    Input:  tT    ` ` Name hh(Type 3Description  tT   ` ` f_name[] hh(*char 3file name  tTc   ` ` mode hh(char 3mode:pp9'w' = write   ` `  "hh(.3pp9'r' = read  tT   ` ` int_level hh(*long 3interchange level: 1, 2, or 3  tT   ` ` ice[] hh(*char 3inline code extension indicator:  tT   ` `  "hh(.3' ' pp9no inline escape sequences are used to designate extended coded character sets(#p  tT   ` `  "hh(.3'E' pp9extensions are used as specified in ISO 2022(#p  tTk   ` ` ccs[] hh(*char 3code character set indicator:   ` `  "hh(.3" " (3 spaces) the   ` `  "hh(.3pp9 International Reference   ` `  "hh(.3pp9 Version of the ISO 646   ` `  "hh(.3pp9 character set is the default   ` `  "hh(.3pp9 for the file; refer to ISO   ` `  "hh(.3pp9 8211 for other values  uS    Output:  tT;    ` ` Name hh(Type 3Description  tT   ` ` int_level hh(*long 3interchange level: 1, 2, or 3  tT   ` ` ice[] hh(*char 3inline code extension indicator:  tT[   ` `  "hh(.3' ' pp9no inline escape sequences are used to designate extended coded character sets(#p  tT   ` `  "hh(.3'E' pp9extensions are used as specified in ISO 2022(#p  tTC   ` ` ccs[] hh(*char 3code character set indicator:   ` `  "hh(.3" " (3 spaces) the   ` `  "hh(.3pp9 International Reference   ` `  "hh(.3pp9 Version of the ISO 646   ` `  "hh(.3pp9 character set is the default   ` `  "hh(.3pp9 for the file; refer to ISO   ` `  "hh(.3pp9 8211 for other values#%0*%%Ԍ tT   ` ` fp hh(**FILE 3file pointer  uS    Returns:  tT    ` ` Name hh(Type 3Description  tT   ` ` beg123file() hh(int h3success flag, returns 1 if successful or 0 if error(#  uS External References: " stc123.h  uT  Requirements:  Function  beg123file() must be called to open and begin  tTa processing of a FIPS PUB 123 DDF. Parameters int_level, ice,  tT) and ccs must be input when opening files in 'write' mode.  tT Function  end123file() must be called to end processing of the data file.(#  uTI  Processing: ` ` X Function  beg123file() opens a data file in 'read' or 'write'  tT mode based on the input parameter mode. The interchange level  tT int_level, inline code extension ice, and code character set  tT ccs are returned by  beg123file() for files opened in 'read'  tTj mode. Parameters int_level, ice, and ccs must be input when opening files in 'write' mode.(# 2&0*%%  uT U3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E beg123rec   Function Name:   beg123rec (#  uT  Purpose: ` ` To begin a data record.(#`  uT"  Arguments: ` `  beg123rec  (*fp)(#`  uS    Input:  tTC    ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  uTc    Output:  none  uS    Returns:  tT   ` ` Name hh(Type 3Description  tT   ` ` beg123rec() hh(int h3success flag, returns 1 if successful or 0 if error(#  uSl  External References: " stc123.h  uT  Requirements:  Function  beg123rec() is an optional function that may be invoked by the application to initiate processing of a new DR. (#  uT  Processing: ` ` X Function  beg123rec() begins processing of a DR. Processing of  tT a previous DR not already ended by  end123rec() is ended by  tT  beg123rec() before processing of the next DR begins. The supporting functions will invoke this optional function as required.(# '0*%%  uT 3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E end123ddrec   Function Name:   end123ddrec(#  uT  Purpose: ` ` To end the data descriptive record.(#`  uT"  Arguments: ` `  end123ddrec (*fp)(#`  uS    Input:  tTC   ` ` Name hh(Type 3Description  tT   ` ` fp hh(**FILE 3file pointer  uTc    Output:  none  uS    Returns:  tT   ` ` Name hh(Type 3Description  tT   ` ` end123ddrec() hh(int h3success flag, returns 1 if successful or 0 if error(#  uSl  External References: " stc123.h  uT  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.(#  uT  Processing: ` ` X Function  end123ddrec() ends processing of a data descriptive record. The function computes the leader and directory and  tTv writes the DDR to file fp. (# >(0*%%  uT 23 tT   #dp@>pQWm@#` `  "hh(.3pp9?  E end123file   Function Name:   end123file(#  uT  Purpose: ` ` To close a FIPS PUB 123 data descriptive file. (#`  uT"  Arguments: ` `  end123file (*fp)(#`  uS    Input:  tTC   ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  uTc    Output:  none  uS    Returns:  tT   ` ` Name hh(Type 3Description  tT   ` ` end123file() hh(int h3success flag, returns 1 if successful or 0 if error(#  uSl  External References: " stc123.h  uT  Requirements:  Function  end123file() must be called to end processing and properly close any DDF previously opened by a call to  tT  beg123file() in either 'read' or 'write' mode.(#  uT  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  tTv structures for fp are freed.(# >)0*%%  uT 23 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E end123rec   Function Name:   end123rec(#  uT  Purpose: ` ` To end processing of a data record.(#`  uT"  Arguments: ` `  end123rec (*fp)(#`  uS    Input:  tTC   ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  uTc    Output:  none  uS    Returns:  tT   ` ` Name hh(Type 3Description  tT   ` ` end123rec() hh(int h3success flag, returns 1 if successful or 0 if error(#  uSl  External References: " stc123.h  uT  Requirements:  Function  end123rec() is an optional function that may be invoked to terminate processing of the current DR. (#  uTU  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*%%  tT G3#dp@>pQWm@#`(#(#VG3.3.2p  @` ` 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:(#`  tT p  @` ` X oX" rd123ddfld() ĩreads the next field of the DDR(#  tT p  @` ` X oX" rd123ddrec() ĩreads the complete DDR, including leader and directory(#  tTh p  @` ` X oX" rd123ddsfld() ĩreads the next subfield of the DDR(#  tT p  @` ` X oX" rd123fld() ĩreads the next DR field (#  tT p  @` ` X oX" rd123rec() ĩreads the next DR, including leader and directory(#  tT p  @` ` X oX" 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*%%  uT ͜0 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E rd123ddfld   Function Name:   rd123ddfld(#  uT  Purpose: ` ` To read a field of the data descriptive record.(#`  uT"  Arguments: ` `  rd123ddfld (*fp,*tag,*rd_str,*status)(#`  uS    Input:  tTC p   ` ` Name hh(Type 3Description(#   tT p   ` ` fp hh(*FILE 3file pointer(#   uSc    Output:  tT    ` ` Name hh(Type 3Description  tT   ` ` tag[] hh(*char 3field tag  tT   ` ` rd_str[] hh(*char h3string consisting of concatenated subfields of current DDR field(#  tTk   ` ` status hh(*int 3status   ` `  "hh(.30 = failure   ` `  "hh(.33 = end of record   ` `  "hh(.34 = end of file   ` `  "hh(.35 = end of field  uS    Returns:  tT p   ` ` Name hh(Type 3Description(#   tT; p   ` ` rd123ddfld() hh(int 3success flag, returns 1 if successful or 0 if error(#  uS  External References: " stc123.h  uT#  Requirements:  Use  rd123ddfld() on DDFs opened in 'read' mode. Parameter  tT rd_str must be declared as a character string large enough to hold the entire DDR field.(#  uTD  Processing: ` ` X Function  rd123ddfld() reads the current DDR field from a file  tT opened in 'read' mode and returns the field in rd_str.(#  ,0*%%  uT ͜3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  ExxK rd123ddrec   Function Name:   rd123ddrec(#  uT  Purpose: ` ` To read the complete data descriptive record.(#`  uT"  Arguments: ` `  rd123ddrec (*fp,*string,*status)(#`  uS    Input:  tTC   ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  uSc    Output:  tT   ` ` Name hh(Type 3Description  tT   ` ` string[] hh(*char.X3string containing complete DDR, including leader and directory(#  tT   ` ` status hh(*int 3status   ` `  "hh(.30 = failure   ` `  "hh(.33 = end of record   ` `  "hh(.34 = end of file  uS    Returns:  tTS    ` ` Name hh(Type 3Description  tT   ` ` rd123ddrec() hh(int h3success flag, returns 1 if successful or 0 if error(#  uS;  External References: " stc123.h  uT  Requirements:  Use  rd123ddrec() on files opened in 'read ' mode. Parameter  tT string must be declared as a character string large enough to hold the entire data descriptive record. Do not use  tT$  rd123ddrec() for a data descriptive record that is expected to  uT exceed a length of MAXSIZ . Use  rd123ddfld() and  rd123ddsfld() since data descriptive record fields and subfields are less  uT} likely to exceed MAXSIZ bytes in length. See paragraph 3.2.2  uTF for information on MAXSIZ .(#  uT  Processing: ` ` X Function  rd123ddrec() reads a complete data descriptive record, populates the appropriate internal FIPS PUB 123 data  tTh" structures, and returns the record in string. (# 0#-0*%%  uT l3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E rd123ddsfld   Function Name:   rd123ddsfld (#  uT  Purpose: ` ` To read a subfield of the data descriptive record. (#`  uT"  Arguments: ` `  rd123ddsfld (*fp,*tag,*rd_str,*status)(#`  uS    Input:  tTC   ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  uSc    Output:  tT   ` ` Name hh(Type 3Description  tT   ` ` tag[] hh(*char 3field tag  tTK   ` ` rd_str[] hh(*char 3subfield string  tT   ` ` status hh(*int 3status   ` `  "hh(.30 = failure   ` `  "hh(.31 = okay   ` `  "hh(.32 = start of record   ` `  "hh(.33 = end of record   ` `  "hh(.34 = end of file   ` `  "hh(.35 = end of field   ` `  "hh(.36 = start of field  uS    Returns:  tT   ` ` Name hh(Type 3Description  tT;   ` ` rd123ddsfld() hh(int h3success flag, returns 1 if successful or 0 if error(#  uS  External References: " stc123.h  uT#  Requirements:  Use  rd123ddsfld() on DDFs opened in 'read' mode. Parameter  tT rd_str must be declared as a character string large enough to hold the DDR subfield.(#  uTD  Processing: ` ` X Function  rd123ddsfld() retrieves the next DDR subfield from a  tT DDF opened in 'read' mode and returns the result in rd_str.(#  .0*%%  uT lǪ3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E rd123fld   Function Name:   rd123fld(#  uT  Purpose: ` ` To read a field of a data record.(#`  uT"  Arguments: ` `  rd123fld (*fp,*tag,*leadid,*rd_str,*str_len,*status)(#`  uS    Input:  tTC   ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  uSc    Output:  tT   ` ` Name hh(Type 3Description  tT   ` ` tag[] hh(*char 3field tag  tTK   ` ` leadid[] "hh(*char 3leader identifier  tT   ` ` rd_str[] hh(*char 3string containing field read  tT   ` ` str_len hh(*long 3byte length of rd_str  tT   ` ` status hh(*int 3status   ` `  "hh(.30 = failure   ` `  "hh(.31 = okay   ` `  "hh(.32 = start of record   ` `  "hh(.33 = end of record   ` `  "hh(.34 = end of file  uS    Returns:  tT   ` ` Name hh(Type 3Description  tT;   ` ` rd123fld() hh(int h3success flag, returns 1 if successful or 0 if error(#  uS  External References: " stc123.h  uT#  Requirements:  Use  rd123fld()  to read a field from a DDF opened in 'read'  tT 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  tT rd_str is sufficiently large to contain the entire uncompressed string.(# #/0*%%Ԍ uT  Processing: ` ` X Function  rd123fld() retrieves the next DR field in file fp.  tT The field is returned as a character string in rd_str with concatenated subfields. (# 00*%%  uT Ǫ@3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E rd123rec Ļ Function Name:   rd123rec(#  uT  Purpose: ` ` To read a complete data record, including leader and directory.(#`  uT"  Arguments: ` `  rd123rec (*fp,*string,*str_len,*status)(#`  uS    Input:  tTC   ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  uSc    Output:  tT   ` ` Name hh(Type 3Description  tT   ` ` string[] hh(*char.X3string containing record read, including leader and directory (#  tT   ` ` str_len hh(*long 3length of string  tTk   ` ` status hh(*int 3status   ` `  "hh(.30 = failure   ` `  "hh(.31 = okay   ` `  "hh(.34 = end of file  uSS    Returns:  tT   ` ` Name hh(Type 3Description  tTs   ` ` rd123rec() hh(int h3success flag, returns 1 if successful or 0 if error(#  uS  External References: " stc123.h  uT[  Requirements:  Use  rd123rec()  to read an entire data record from a DDF opened  tT$ in 'read' mode. The parameter string must be declared as a character string large enough to hold the entire DR. Do not  tT use  rd123rec() for a DR that is expected to exceed a length of  uT|  MAXSIZ . Use  rd123fld() and  rd123sfld() since DR fields and  uTE subfields are less likely to exceed MAXSIZ bytes in length.  uT See paragraph 3.2.2 for information on MAXSIZ .(#  uT!  Processing: ` ` X Function  rd123rec() reads the next DR from file fp and returns  tTh" the record in string. Adjacent fixedlength bit fields/subfields are returned in compressed format. (# #10*%%  uT @3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E rd123sfld ļ Function Name:   rd123sfld (#  uT  Purpose: ` ` To read a subfield of a data record. (#`  uT"  Arguments: ` `  rd123sfld (*fp,*tag,*leadid,*rd_str,*str_len,*status) (#`  uS    Input:  tTC   ` ` Name "hh(Type 3Description  tT   ` ` fp "hh(*FILE 3file pointer  uSc    Output:  tT   ` ` Name "hh(Type 3Description  tT   ` ` tag[] "hh(*char 3field tag  tTK   ` ` leadid[] "hh(*char 3leader identifier  tT   ` ` rd_str[] "hh(*char h3subfield string (#  tT   ` ` str_len "hh(*long 3byte length of rd_str  tT   ` ` status "hh(*int 3status   ` `  "hh(.30 = failure   ` `  "hh(.31 = okay   ` `  "hh(.32 = start of record   ` `  "hh(.33 = end of record   ` `  "hh(.34 = end of file   ` `  "hh(.35 = end of field   ` `  "hh(.36 = start of field  uS    Returns:  tT;   ` ` Name "hh(Type 3Description  tT   ` ` rd123sfld() hh(int h3success flag, returns 1 if successful or 0 if error(#  uS#  External References: " stc123.h  uT   Requirements:  Use  rd123sfld()  to read a subfield from a DDF opened in 'read'  tT| mode. The parameter rd_str must be declared as a character string large enough to hold the DR subfield.(#  uT  Processing: ` ` X Function  rd123sfld() retrieves the next DR subfield from file  tT! fp and returns the result in rd_str. (# !20*%%  tT  g3`(#(#V 3.3.3p  @` ` 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:(#`  tT p  @` ` X oX" wr123ddfld() ĩwrites a DDR field(#  tT p  @` ` X oX" wr123ddrec() ĩaccepts a string containing the complete DDR, including leader and directory, and writes the DDR to the output file(#  tT p  @` ` X oX" wr123ddsfld() ĩwrites a DDR subfield (#  tT p  @` ` X oX" wr123fld() ĩwrites a DR field (#  tTp p  @` ` X oX" wr123rec() ĩwrites a complete DR, including leader and directory(#  tT p  @` ` X oX" wr123sfld() ĩwrites a DR subfield. (# p  @` ` The usage of these functions is described in the following paragraphs.(#`  30*%%  uT g0 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E wr123ddfld   Function Name:   wr123ddfld (#  uT  Purpose: ` ` To write a field to the data descriptive record.(#`  uT"  Arguments: ` `  wr123ddfld (*fp,*tag,*wr_str,option)(#`  uS    Input:  tTC   ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  tT   ` ` tag[] hh(*char 3field tag  tTc   ` ` wr_str[] hh(*char 3string containing a DDR field  tT+   ` ` option hh(int 3write field option   ` `  "hh(.31 = okay   ` `  "hh(.32 = start of record   ` `  "hh(.33 = end of record   ` `  "hh(.34 = end of file  uT    Output:  none  uSl    Returns:  tT   ` ` Name hh(Type 3Description  tT   ` ` wr123ddfld() hh(int h3success flag, returns 1 if successful or 0 if error(#  uS  External References: " stc123.h  uTt  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.(#  uT%  Processing: ` ` X Function  wr123ddfld() writes the DDR field contained in wr_str  tT to the file fp. (# 40*%%  uT T3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E wr123ddrec Ľ Function Name:   wr123ddrec(#  uT  Purpose: ` ` To write a complete data descriptive record, including leader and directory.(#`  uT  Arguments: ` `  wr123ddrec (*fp,*string,*status)(#`  uS{    Input:  tT    ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3pointer to file pointer  tT+   ` ` string[] hh(*char.X3string containing the complete DDR, including leader and directory(#  uS    Output:  tT   ` ` Name hh(Type 3Description  tT   ` ` status hh(*int 3status  tTk    30 = failure   ` `  "hh(.31 = okay  uS    Returns:  tTS   ` ` Name hh(Type 3Description  tT   ` ` wr123ddrec() hh(int h3success flag, returns 1 if successful or 0 if error(#  uS;  External References: " stc123.h  uT  Requirements:  Use  wr123ddrec() to write a complete DDR of a DDF opened in  tT 'write' mode. The parameter status   is set to 'failure' if an  tT\ error is encountered during processing. Follow  wr123ddrec   tT$ with a call to  end123ddrec  to end processing of the DDR.(#  uT  Processing: ` ` X Function  wr123ddrec() writes the string contained in wr_str to  tT} file fp. It then backs up and rereads the DDR to correctly populate the FIPS PUB 123 internal data structures.(#  50*%%  uT T3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E wr123ddsfld   Function Name:   wr123ddsfld (#  uT  Purpose: ` ` To write a subfield to the data descriptive record.(#`  uT"  Arguments: ` `  wr123ddsfld (*fp,*tag,*wr_str,option)(#`  uS    Input:  tTC   ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  tT   ` ` tag[] hh(*char 3field tag  tTc   ` ` wr_str[] hh(*char 3string containing a DDR field  tT+   ` ` option hh(int 3write subfield option   ` `  "hh(.31 = okay   ` `  "hh(.32 = start of record   ` `  "hh(.33 = end of record   ` `  "hh(.34 = end of file   ` `  "hh(.35 = end of field   ` `  "hh(.36 = start of field  uTk    Output:  none  uS    Returns:  tT   ` ` Name hh(Type 3Description  tT   ` ` wr123ddsfld() hh(int h3success flag, returns 1 if successful or 0 if error(#  uSt  External References: " stc123.h  uT  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.(#  uT#  Processing: ` ` X Function  wr123ddsfld() writes a DDR subfield to file fp. (# #60*%%  uT P3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E wr123fld Ļ Function Name:   wr123fld (#  uT  Purpose: ` ` To write a field to a data record.(#`  uT"  Arguments: ` `  wr123fld (*fp,*tag,leadid,*wr_str,*str_len,*option)(#`  uS    Input:  tTC   ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  tT   ` ` tag[] hh(*char 3field tag  tTc   ` ` leadid hh(char 3leader identifier: 'D' or 'R'  tT+   ` `  "hh(.3'D' pp9a leader and directory will be found in subsequent DR(#p  tT   ` `  "hh(.3'R' pp9the leader and directory will not be found in subsequent DRs; the leader and directory of the current DR will apply to subsequent DRs(#p  tT   ` ` wr_str[] hh(*char 3string containing a DR field  tTk   ` ` str_len hh(long 3length of wr_str  tT3   ` ` option hh(int 3write field option   ` `  "hh(.31 = okay   ` `  "hh(.32 = start of record   ` `  "hh(.33 = end of record   ` `  "hh(.34 = end of file  uT    Output:  none  uSt    Returns:  tT   ` ` Name hh(Type 3Description  tT   ` ` wr123fld() hh(int h3success flag, returns 1 if successful or 0 if error(#  uS  External References: " stc123.h  uT|  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.(# #70*%%Ԍ tT   ` `  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.(#  uT   Processing: ` ` X Function  wr123fld() writes a DR field to file fp.(# 80*%%  uT P3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E wr123rec Ļ Function Name:   wr123rec(#  uT  Purpose: ` ` To write a complete data record, including leader and directory.(#`  uT"  Arguments: ` `  wr123rec (*fp,*string,*str_len,*status)(#`  uS    Input:  tTC   ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  tTc   ` ` string[] hh(*char.X3string containing complete data record, including leader and directory(#  tT   ` ` str_len hh(*long 3length of string  uS    Output:  tT   ` ` Name hh(Type 3Description  tT3   ` ` status hh(*int 3status   ` `  "hh(.30 = failure   ` `  "hh(.31 = okay  uSS    Returns:  tT   ` ` Name hh(Type 3Description  tTs   ` ` wr123rec() hh(int h3success flag, returns 1 if successful or 0 if error(#  uS  External References: " stc123.h  uT[  Requirements:  Use  wr123rec() to write an entire data record to a DDF opened in 'write' mode. (#  uT  Processing: ` ` X Function  wr123rec() writes the DR contained in string to file  tT} fp. A status of 'failure' is returned if an error is encountered during processing. (# E90*%%  uT 3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E wr123sfld ļ Function Name:   wr123sfld (#  uT  Purpose: ` ` To write a subfield of a data record. (#`  uT"  Arguments: ` `  wr123sfld (*fp,*tag,leadid,*wr_str,*str_len,*option) (#`  uS    Input:  tTC   ` ` Name "hh(Type 3Description  tT   ` ` fp "hh(*FILE 3file pointer  tT   ` ` tag[] "hh(*char 3field tag  tTc   ` ` leadid "hh(char 3leader identifier  tT+   ` `  "hh(.3'D' pp9a leader and directory will be found in subsequent DR(#p  tT   ` `  "hh(.3'R' pp9the leader and directory will not be found in subsequent DRs; the leader and directory of the current DR will apply to subsequent DRs(#p  tT   ` ` wr_str[] "hh(*char h3string containing a DR subfield (#  tTk   ` ` str_len "hh(*long 3length of wr_str  tT3   ` ` option "hh(*int 3write subfield option   ` `  "hh(.31 = okay   ` `  "hh(.32 = start of record   ` `  "hh(.33 = end of record   ` `  "hh(.34 = end of file   ` `  "hh(.35 = end of field   ` `  "hh(.36 = start of field  uTs    Output:  none  uS    Returns:  tT   ` ` Name "hh(Type 3Description  tT$   ` ` wr123sfld() hh(int h3success flag, returns 1 if successful or 0 if error(#  uS|  External References: " stc123.h  uT  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. (#  tTx   ` `  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. (#  uT  Processing: ` ` X Function  wr123sfld() writes the DR subfield contained in  tTa wr_str to file fp. (# ) ;0*%%  tT G3#dp@>pQWm@#`(#(#VG3.3.4p  @` ` 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,  tT` or subfield with an 'end of file' option upon detecting an 'end of file' condition on the input userspecified data model.(#`  tT p   @` ` The backup functions include the following:(#`  tT< p  @` ` X oX" bak123fld() ĩbacks up the currency pointer to the beginning of the last field read or written(#  tT p  @` ` X oX" bak123rec() ĩbacks up the currency pointer to the beginning of the last record read or written(#  tTD p  @` ` X oX" 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*%%  uT ;0 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E bak123fld ļ Function Name:   bak123fld (#  uT  Purpose: ` ` To back up to the beginning of the last DR field read or written. (#`  uT"  Arguments: ` `  bak123fld (*fp,*status)(#`  uS    Input:  tTC   ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  uSc    Output:  tT   ` ` Name "hh(Type.3Description  tT   ` ` status hh(*int 3status   ` `  "hh(.30 = failure   ` `  "hh(.31 = okay   ` `  "hh(.32 = start of record   ` `  "hh(.33 = end of record  uS3    Returns:  tT   ` ` Name hh(Type 3Description  tTS   ` ` bak123fld() hh(int h3success flag, returns 1 if successful or 0 if error(#  uS  External References: " stc123.h  uT;   Requirements:  Reading or writing a DR or any part of a DR within a file must occur prior to backing up within the file.(#  uT  Processing: ` ` X Function  bak123fld() backs up to the beginning of the last  tT] field read or written for file fp. For a DDF opened in  tT% 'write' mode,  bak123fld() deletes the current field, modifies the field pointer to the end of the previous field, and  tT 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  tT is returned in status. This field may now be reread.(#  tTe" p  @` ` X A status of 'failure' is returned when backing up while positioned at the first DR field in a DDF.(# -#=0*%%  uT ;j3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E bak123rec ļ Function Name:   bak123rec (#  uT  Purpose: ` ` To back up to the beginning of the last DR read or written.(#`  uT"  Arguments: ` `  bak123rec (*fp,*status)(#`  uS    Input:  tTC   ` ` Name "hh(Type.3Description  tT   ` ` fp hh(*FILE 3file pointer  uSc    Output:  tT   ` ` Name "hh(Type.3Description  tT   ` ` status hh(*int 3status   ` `  "hh(.30 = failure   ` `  "hh(.31 = okay  uS    Returns:  tT3   ` ` Name hh(Type 3Description  tT   ` ` bak123rec() hh(int h3success flag, returns 1 if successful or 0 if error(#  uS  External References: " stc123.h  uT  Requirements:  Reading or writing a DR or any part of a DR within a file must occur prior to backing up within the file.(#  uT  Processing: ` ` X Function  bak123rec() backs up to the beginning of the last DR  tT read or written for file fp. For a DDF opened in "write"  tT mode,  bak123rec() deletes the current record, sets the record pointer to the start of the record, and returns the  tT% appropriate position in status. For a file opened in 'read' mode, the record pointer is backed up to the start of the  tT 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*%%  uT j 3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E bak123sfld Ľ Function Name:   bak123sfld (#  uT  Purpose: ` ` To back up to the beginning of the last DR subfield read or written.(#`  uT  Arguments: ` `  bak123sfld (*fp,*status) (#`  uS{    Input:  tT    ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  uS+    Output:  tT   ` ` Name hh(Type 3Description  tTK   ` ` status hh(*int 3status   ` `  "hh(.30 = failure   ` `  "hh(.31 = okay   ` `  "hh(.32 = start of record   ` `  "hh(.36 = start of field  uS    Returns:  tT   ` ` Name hh(Type 3Description  tT   ` ` bak123sfld() hh(int h3success flag, returns 1 if successful or 0 if error(#  uSs  External References: " stc123.h  uT  Requirements:  Reading or writing a DR or any part of a DR within a file must occur prior to backing up within the file.(#  uT\  Processing: ` ` X Function  bak123sfld() backs up to the beginning of the last  tT% subfield that was read or written for the file fp. For a DDF  tT opened in 'write' mode,  bak123sfld() deletes the current subfield, sets the pointer to the previous subfield, and  tT} returns the appropriate position in status. For a DDF opened in 'read' mode, the subfield pointer is changed to the  tT previous subfield read and the position is returned in status.  tT A status of 'failure' is returned when attempting to back up while positioned at the first subfield in a DDF.(# !?0*%%  tT  GG3#dp@>pQWm@#`(#(#VG3.3.5p  @` ` 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:(#`  tT` p  @` ` X oX" chk123fld() ĩretrieves the format and description of the current DR field(#  tT p  @` ` X oX" chk123nfld() ĩretrieves the format and description of the next DR field to be processed(#  tTh p  @` ` X oX" chk123nrec() ĩretrieves the format and description of the next DR to be processed(#  tT p  @` ` X oX" chk123nsfld() ĩretrieves the format and description of the next subfield to be processed(#  tTp p  @` ` X oX" chk123rec() ĩretrieves the format and description of the current DR(#  tT p  @` ` X oX" 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.  tT That is, if you are processing by record, use  chk123rec  or  tT  chk123nrec ; if you are processing by field, use  chk123fld  or  tT!  chk123nfld ; if you are processing by subfield, use  chk123sfld  or  tT(#  chk123nsfld . The usage of these functions is described in the following paragraphs.(#` T$@0*%%  uT GK0 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E chk123fld ļ Function Name:   chk123fld (#  uT  Purpose: ` ` To retrieve the description of the last DR field read or written. (#`  uT"  Arguments: ` `  chk123fld (*fp,*fdtag,*fdlen,**fdname,*fdcntrl,*fmts,*labs) (#`  uS    Input:  tTC   ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  uSc    Output:  tT   ` ` Name hh(Type 3Description  tT   ` ` fdtag[] hh(*char 3field tag  tTK   ` ` fdlen[] hh(*char 3field length  tT   ` ` fdname[] hh(**char 3field name  tT   ` ` fdcntrl[] hh(*char 3field controls  tT   ` ` fmts[] hh(*char 3field format string  tTk   ` ` labs[] hh(*char 3field labels  uS    Returns:  tT   ` ` Name hh(Type 3Description  tT   ` ` chk123fld() hh(int h3success flag, returns 1 if successful or 0 if error(#  uSs  External References: " stc123.h  uT   Requirements:  Use  chk123fld() after reading or writing a DR field and while the DR is current; that is, before ending the DR with  tT  end123rec() or before beginning another DR with  beg123rec() .  tT\ The output character string fdname is dynamically allocated by  tT$  chk123fld() ; the application must release this variable prior  tT to a subsequent call to  chk123fld() .(#  uT|  Processing: ` ` X Function  chk123fld() returns the tag, length, name, field controls, format, and labels of the last field read or written  tT for the current DR of file fp. (#  A0*%%  uT K3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E chk123nfld Ľ   Function Name:   chk123nfld (#  uT  Purpose: ` ` To retrieve the description of the next DR field to be read or written. (#`  uT  Arguments: ` `  chk123nfld (*fp,*tag,*fdlen,**fdname,*fdcntrl,*fmts,*labs) (#`  uS{    Input:  tT    ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  uS+    Output:  tT   ` ` Name hh(Type 3Description  tTK   ` ` tag[] hh(*char 3field tag  tT   ` ` fdlen[] hh(*char 3field length  tT   ` ` fdname[] hh(**char 3field name  tT   ` ` fdcntrl[] hh(*char 3field controls  tTk   ` ` fmts[] hh(*char 3field format string  tT3   ` ` labs[] hh(*char 3field labels  uS    Returns:  tTS   ` ` Name hh(Type 3Description  tT   ` ` chk123nfld() hh(int h3success flag, returns 1 if successful or 0 if error(#  uS;  External References: " stc123.h  uT  Requirements:  Use  chk123nfld() after reading or writing a DR field. After  tT writing a field, invoke  chk123nfld()  before ending the DR with  tT\  end123rec() or beginning another DR with  beg123rec() . If you  tT$ invoke  chk123nfld() after reading a field, the description of the next field is retrieved, regardless of record boundaries.  tT The output character string fdname is dynamically allocated by  tT|  chk123nfld() ; the application program must release this  tTD variable prior to a subsequent call to  chk123nfld() .(#  uT  Processing: ` ` X Function  chk123nfld() returns the tag, length, name, field controls, format, and labels of the next field to be read or  tTe" the last DR field written to file fp. (# e"B0*%%  uT 3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E chk123nrec Ľ Function Name:   chk123nrec (#  uT  Purpose: ` ` To retrieve the description of the next data record to be read or the last data record written. (#`  uT  Arguments: ` `  chk123nrec (*fp,*reclen,*leadid,*descr) (#`  uS{    Input:  tT    ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  uS+    Output:  tT   ` ` Name hh(Type 3Description  tTK   ` ` reclen hh(*long 3record length  tT   ` ` leadid hh(*char 3leader identifier  tT   ` ` descr hh(*char 3description  uSk    Returns:  tT   ` ` Name hh(Type 3Description  tT   ` ` chk123nrec() hh(int h3success flag, returns 1 if successful or 0 if error(#  uS  External References: " stc123.h  uTs  Requirements:  For a DDF opened in 'read' mode, use  chk123nrec() to obtain the format and description of the next record to be read. For  tT 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  tT\  end123rec() or before beginning another DR with  beg123rec() . (#  uT  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"C0*%%  uT  3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E chk123nsfld ľ Function Name:   chk123nsfld (#  uT  Purpose: ` ` To retrieve the description of the next DR subfield to be read or written. (#`  uT  Arguments: ` `  chk123nsfld (*fp,*tag,*descr,*frmt) (#`  uS{    Input:  tT    ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  uS+    Output:  tT   ` ` Name hh(Type 3Description  tTK   ` ` tag[] hh(*char 3field tag  tT   ` ` descr[] hh(*char 3output description of subfield  tT   ` ` frmt[] hh(*char 3format  uSk    Returns:  tT   ` ` Name hh(Type 3Description  tT   ` ` chk123nsfld() hh(int h3success flag, returns 2 if end of field or 1 if successful or 0 if error(#  uS  External References: " stc123.h  uT;  Requirements:  Use  chk123nsfld() after reading or writing a DR subfield.  tT After writing a subfield, invoke  chk123nsfld  before ending the  tT DR with  end123rec() or beginning another DR with  beg123rec() .  tT After reading a subfield,  chk123nsfld()  returns the next subfield description, regardless of field or record boundaries.(#  uT  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.(# #D0*%%Ԍ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  tTX  chk123nslfd()  is 2.(#   ` `  The description content depends upon the type of data structure defined in the DDR for the next subfield. For  tT@ vector data structures, descr contains a single vector label;  tT for Cartesian data structures, descr contains a vector label from each Cartesian label delimited by the character '!'. No  tT label is placed in descr if the Cartesian label contains a null vector label. A leading '!' or adjacent '!'s within  tT( descr represent a null vector label(s).(#  E0*%%  uT  3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E chk123rec ļ Function Name:   chk123rec (#  uT  Purpose: ` ` To retrieve the description of the last data record read or written.(#`  uT  Arguments: ` `  chk123rec (*fp,*reclen,*leadid,*descr) (#`  uS{    Input:  tT    ` ` Name "hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  uS+    Output:  tT   ` ` Name hh(Type 3Description  tTK   ` ` reclen hh(*long 3record length  tT   ` ` leadid[] hh(*char 3leader identifier  tT   ` ` descr[] hh(*char 3description  uSk    Returns:  tT   ` ` Name hh(Type 3Description  tT   ` ` chk123rec() hh(int h3success flag, returns 1 if successful or 0 if error(#  uS  External References: " stc123.h  uTs  Requirements:  Use  chk123rec() after reading or writing a data record and while that DR is current; that is, before ending the DR with  tT  end123rec() or before beginning another DR with  beg123rec() . (#  uT  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). (#  F0*%%  uT 3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E chk123sfld Ľ Function Name:   chk123sfld (#  uT  Purpose: ` ` To retrieve the description of the last DR subfield read or written. (#`  uT  Arguments: ` `  chk123sfld (*fp,*tag,*descr,*frmt) (#`  uS{    Input:  tT    ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  tTc   ` ` tag[] hh(*char 3field tag  uS    Output:  tT   ` ` Name hh(Type 3Description  tT   ` ` descr[] hh(*char 3output label/description of subfield  tT   ` ` frmt[] hh(*char 3format  uSk    Returns:  tT   ` ` Name hh(Type 3Description  tT   ` ` chk123sfld() hh(int h3success flag, returns 1 if successful or 0 if error(#  uS  External References: " stc123.h  uTs  Requirements:  Use  chk123sfld() after reading or writing a DR subfield and while the DR is current; that is, before ending the DR with  uT  end123rec() or before beginning another DR with  beg123rec() .(#  uT 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.(# #G0*%%Ԍ  ` `  The description content depends upon the type of data structure defined in the DDR for the corresponding subfield.  tT For vector data structures, descr contains a single vector  tTX label; for Cartesian data structures, descr contains a vector label from each Cartesian label delimited by the character  tT '!'. No label is placed in descr if the Cartesian label contains a null vector label. A leading '!' or adjacent '!'s  tTx within descr represent a null vector label(s).(# @H0*%%  tT G3#dp@>pQWm@#`(#(#VG3.3.6p  @` ` 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:(#`  tT p  @` ` X oX" er123ddfld() ĩerases the last DDR field written(#  tT4 p  @` ` X oX" er123ddrec() ĩerases the DDR record(#  tT` p  @` ` X oX" er123ddsfld() ĩerases the last DDR subfield written.(# p  @` ` The erase functions may be used only while processing the DDR; that  tT is, before the DDR is ended with    end123ddrec() . If  er123ddrec()  is  tT called after end123ddrec() , the DDR and any subsequent DRs written  tT< will be erased. If  er123ddfld()  or  er123ddsfld()  is called after  tTh  end123ddrec() , subsequent errors may be encountered while processing DRs. (#` p  @` ` The following paragraphs describe the usage of these functions.(#` pI0*%%  uT !0 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E er123ddfld Ľ Function Name:   er123ddfld (#  uT  Purpose: ` ` To erase the last field written to the data descriptive record.(#`  uT"  Arguments: ` `  er123ddfld (*fp,*status) (#`  uS    Input:  tTC   ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  uSc    Output:  tT   ` ` Name hh(Type 3Description  tT   ` ` status hh(*int 3status   ` `  "hh(.30 = failure   ` `  "hh(.32 = start of record   ` `  "hh(.36 = start of field  uSk    Returns:  tT   ` ` Name hh(Type 3Description  tT   ` ` er123ddfld() hh(int h3success flag, returns 1 if successful or 0 if error(#  uS  External References: " stc123.h  uTs  Requirements:  Function  er123ddfld() may be invoked only for a DDF opened in 'write' mode during processing of the data descriptive record;  uT that is, prior to invoking function  end123ddrec() .(#  uT Processing: ` ` X Function  er123ddfld() erases the last DDR field written to  tT^ file fp. The position of the DDR field is returned in status.  tT& A status of 'failure' is returned when attempting to erase a DDR field that does not exist.(# ~J0*%%  uT !;%3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E er123ddrec Ľ Function Name:   er123ddrec(#  uT  Purpose: ` ` To erase the entire data descriptive record.(#`  uT"  Arguments: ` `  er123ddrec (*fp,*status)(#`  uS    Input:  tTC   ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  uSc    Output:  tT   ` ` Name hh(Type 3Description  tT   ` ` status hh(*int 3status   ` `  "hh(.30 = failure   ` `  "hh(.32 = start of record  uS    Returns:  tT3   ` ` Name hh(Type 3Description  tT   ` ` er123ddrec() hh(int h3success flag, returns 1 if successful or 0 if error(#  uS  External References: " stc123.h  uT  Requirements:  Function  er123ddrec() may be invoked only for a DDF opened in 'write' mode during processing of the data descriptive record;  tT< that is, prior to invoking  end123ddrec() . Invoking  tT  er123ddrec() after ending data descriptive record processing  tT with  end123ddrec() and beginning DR processing will cause all DRs written to be lost.(#  uT$  Processing: ` ` X Function  er123ddrec() erases the data descriptive record from  tT file fp and returns a status of 'start of record'.(# K0*%%  uT ;%c)3 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E er123ddsfld ľ Function Name:   er123ddsfld (#  uT  Purpose: ` ` To erase a subfield of the data descriptive record.(#`  uT"  Arguments: ` `  er123ddsfld  (*fp,*status) (#`  uS    Input:  tTC   ` ` Name hh(Type 3Description  tT   ` ` fp hh(*FILE 3file pointer  uSc    Output:  tT   ` ` Name hh(Type 3Description  tT   ` ` status hh(*int 3status   ` `  "hh(.30 = failure   ` `  "hh(.31 = okay   ` `  "hh(.32 = start of record   ` `  "hh(.35 = end of field   ` `  "hh(.36 = start of field  uS    Returns:  tT   ` ` Name hh(Type 3Description  tT   ` ` er123ddsfld() hh(int h3success flag, returns 1 if successful or 0 if error(#  uSs  External References: " stc123.h  uT  Requirements:  Function  er123ddsfld() may be invoked only for a DDF opened in 'write' mode during processing of a data descriptive  tT record; that is, prior to invoking  end123ddrec() .(#  uT$  Processing: ` ` X Function  er123ddsfld() erases the last DDR subfield written  tT to file fp. The position of the erased DDR subfield is  tT returned in status. A status of 'failure' is returned when attempting to erase a DDR subfield that does not exist.(# EL0*%%  tT c)G-3#dp@>pQWm@#`(#(#VG3.3.7p  @` ` 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:(#`  tT p  @` ` X oX" g123order() ĩreturns the byte order of the current operating architecture(#  tT p  @` ` X oX" 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(#  tTh p  @` ` X oX" s123tol() ĩconverts a character string to a long integer, optionally reversing the order of the bytes of the string prior to converting.(# A 6"xJ dd0Nx0**0a#dp@>pQWm@#   Figure 10 Binary Data Representation.  S #X~xP7qXP#ppp@ X0x04030201 = unsigned 6730598510Ɛ pppBig Endian:Ɛp #ixP7AP#  }KK ppp@ High Order Byte >` "Low Order ByteƐ  }K ppp@ Most Significant Byte >` "Least Significant ByteƐ  }K ppp@ Byte #1` ` Byte #2"Byte #3.Byte #4Ɛ  }K  ppp@ 0x04XX` ` 0x03X X"0x02Xhh(X.0x01Ɛ  }Kk  ppp@ 0000 0100` ` 0000 0011"0000 0010.0000 0001 Ɛ  S #X~xP7qXP#pppLittle Endian:Ɛp #ixP7AP#  }Kt ppp@ Low Order Byte >` "High Order ByteƐ  }K< ppp@ Least Significant Byte >` "Most Significant ByteƐ  }K ppp@ Byte #1` ` Byte #2"Byte #3.Byte #4Ɛ  }K  ppp@ 0x01XX` ` 0x02X X"0x03Xhh(X.0x04Ɛ  }K  ppp@ 0000 0001` ` 0000 0010"0000 0011.0000 0100 Ɛ  S #X~xP7qXP#pppMiddle Endian (left to right):Ɛp #ixP7AP#  }K ppp@ ©> Low Order Byte ` "High Order Byte > Ɛ  }Ke ppp@ ©> Least Sig. Byte ` "Most Sig. Byte >Ɛ  }K- ppp@ Byte #1` ` Byte #2"Byte #3.Byte #4Ɛ  }K  ppp@ 0x02XX` ` 0x01X X"0x04Xhh(X.0x03Ɛ  }K  ppp@ 0000 0010` ` 0000 0001"0000 0100.0000 0011Ɛ  }K  ppp@ 16 bit big endian X"16 bit big endianƐ ppp@ ©32 bit little endianƐ  S #X~xP7qXP#pppMiddle Endian (right to left):Ɛp #ixP7AP#  }K ppp@ < High Order Byte ` "Low Order Byte < Ɛ  }KV ppp@ < Most Sig. Byte ` "Least Sig. Byte <Ɛ  }K ppp@ Byte #1` ` Byte #2"Byte #3.Byte #4Ɛ  }K  ppp@ 0x03XX` ` 0x04X X"0x01Xhh(X.0x02Ɛ  }K  ppp@ 0000 0011` ` 0000 0100"0000 0001.0000 0010Ɛ  }Kv  ppp@ 16 bit little endian X"16 bit little endianƐ ppp@ ©32 bit big endianƐ p  @` ` Binary data are stored as big endian, little endian, or middle  tTD 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,  tT use the reverse parameter when calling  s123tol()  or  l123tos()  to  tT reverse the order of the bytes.1 (#`  tT! 1p  The Spatial Data Transfer Standard (FIPS PUB 173) specifies that all binary data be represented in big endian format.(#  0T$M0*%%'#O-AN0 $(#(#(#(#A'#$0N0*%%'#O-AN0  uT -20 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E g123order ļ Function Name:   g123order(#   tT Purpose:` ` To return the byte order of the current machine.  tT! Arguments:` `  g123order (*order)  uT    Input:  none  uSB    Output:   ` ` Name Type Description  tTb   ` ` order *int byte order   ` `  "hh(.0 = little endian   ` `  "hh(.(least significant byte first)   ` `  "hh(.1 = big endian   ` `  "hh(.(most significant byte first)   ` `  "hh(.2 = middle endian  uS    Returns:   ` ` Name Type Description  tT   ` ` g123order()  int success flag returns 1  uT  External References: ` "none(#  uT  Requirements:  Based on the value of order returned by  g123order , determine  tT whether subsequent calls to  l123tos  or  s123tol  will require byte reversal. (#  uT<  Processing ` ` X Function  g123order() places a long integer test value into memory and returns the byte ordering of the current machine.(# ]O0*%%  uT 2g53 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E l123tos ĺ Function Name:   l123tos(#   tT Purpose:` ` To convert a long integer to a 4byte character string and change its byte ordering when specified.(#`  tT Arguments:` `  l123tos  (num,*string,reverse)  uSy    Input:   ` ` Name Type Description  tT   ` ` num long number to be converted  tTa   ` ` reverse int reverse byte order flag   ` `  "hh(.1 = reverse   ` `  "hh(.0 = do not reverse  uS    Output:   ` ` Name Type Description  tT   ` ` string[] *char 4byte character string  uS1    Returns:   ` ` Name Type Description  tTQ   ` ` l123tos()  int success flag returns 1  uT  External References: ` "none(#  uT:  Requirements:  Declare the output character string to be 4 bytes long. Specify whether byte order reversal is required based on a  tT prior call to  g123order .(#  uT[  Processing: ` ` X Function  l123tos() moves a long integer value to a 4byte  tT$ 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)  tT| and vice versa as specified by reverse.(# DP0*%%  uT g593 tT #dp@>pQWm@#  ` `  "hh(.3pp9?  E s123tol ĺ Function Name:   s123tol(#   uT  Purpose: ` ` To convert a 4byte character string to a long integer and change its byte ordering when specified.(#`  uT  Arguments: ` `  s123tol  (*string,*num,reverse)(#`  uS{    Input:  tT    ` ` Name Type .Description  tT   ` ` string[]  *char .character string  tTc p  ` ` reverse  int .reverse byte order flag(#  p  @` ` X X"Xhh(X.1 = reverse(#   ` ` X X"Xhh(X.0 = do not reverse(#  uS    Output:  tT   ` ` Name Type .Description  tT   ` ` num *long .converted number  uS3    Returns:  tT   ` ` Name Type .Description  tTS   ` ` s123tol()  int .success flag returns 1  uT  External References: ` "none(#  uT<  Requirements:    Declare the input string to be 4 bytes long. Specify the  tT value of reverse based on a prior call to  g123order .(#  uT  Processing: ` ` X Function  s123tol() reverses the order of the bytes, if  tT^ specified by reverse,and moves the 4byte character string to a long integer variable.(# Q0*%%  tT 44.  ` ` MANAGEMENT OF PROGRAM  tTX 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  tT 4.2  ` ` SOFTWARE CHANGE NOTICE   ` ` Configuration Management Office   ` ` National Mapping Division   ` ` U.S. Geological Survey   ` ` 510 National Center   ` ` Reston, VA 22092