%!PS-Adobe-2.0 %%Creator: dvips(k) 5.86 Copyright 1999 Radical Eye Software %%Title: cfitsio.dvi %%Pages: 168 %%PageOrder: Ascend %%BoundingBox: 0 0 612 792 %%EndComments %DVIPSWebPage: (www.radicaleye.com) %DVIPSCommandLine: dvips -N0 cfitsio %DVIPSParameters: dpi=600, compressed %DVIPSSource: TeX output 2004.12.02:1427 %%BeginProcSet: texc.pro %! /TeXDict 300 dict def TeXDict begin/N{def}def/B{bind def}N/S{exch}N/X{S N}B/A{dup}B/TR{translate}N/isls false N/vsize 11 72 mul N/hsize 8.5 72 mul N/landplus90{false}def/@rigin{isls{[0 landplus90{1 -1}{-1 1}ifelse 0 0 0]concat}if 72 Resolution div 72 VResolution div neg scale isls{ landplus90{VResolution 72 div vsize mul 0 exch}{Resolution -72 div hsize mul 0}ifelse TR}if Resolution VResolution vsize -72 div 1 add mul TR[ matrix currentmatrix{A A round sub abs 0.00001 lt{round}if}forall round exch round exch]setmatrix}N/@landscape{/isls true N}B/@manualfeed{ statusdict/manualfeed true put}B/@copies{/#copies X}B/FMat[1 0 0 -1 0 0] N/FBB[0 0 0 0]N/nn 0 N/IEn 0 N/ctr 0 N/df-tail{/nn 8 dict N nn begin /FontType 3 N/FontMatrix fntrx N/FontBBox FBB N string/base X array /BitMaps X/BuildChar{CharBuilder}N/Encoding IEn N end A{/foo setfont}2 array copy cvx N load 0 nn put/ctr 0 N[}B/sf 0 N/df{/sf 1 N/fntrx FMat N df-tail}B/dfs{div/sf X/fntrx[sf 0 0 sf neg 0 0]N df-tail}B/E{pop nn A definefont setfont}B/Cw{Cd A length 5 sub get}B/Ch{Cd A length 4 sub get }B/Cx{128 Cd A length 3 sub get sub}B/Cy{Cd A length 2 sub get 127 sub} B/Cdx{Cd A length 1 sub get}B/Ci{Cd A type/stringtype ne{ctr get/ctr ctr 1 add N}if}B/id 0 N/rw 0 N/rc 0 N/gp 0 N/cp 0 N/G 0 N/CharBuilder{save 3 1 roll S A/base get 2 index get S/BitMaps get S get/Cd X pop/ctr 0 N Cdx 0 Cx Cy Ch sub Cx Cw add Cy setcachedevice Cw Ch true[1 0 0 -1 -.1 Cx sub Cy .1 sub]/id Ci N/rw Cw 7 add 8 idiv string N/rc 0 N/gp 0 N/cp 0 N{ rc 0 ne{rc 1 sub/rc X rw}{G}ifelse}imagemask restore}B/G{{id gp get/gp gp 1 add N A 18 mod S 18 idiv pl S get exec}loop}B/adv{cp add/cp X}B /chg{rw cp id gp 4 index getinterval putinterval A gp add/gp X adv}B/nd{ /cp 0 N rw exit}B/lsh{rw cp 2 copy get A 0 eq{pop 1}{A 255 eq{pop 254}{ A A add 255 and S 1 and or}ifelse}ifelse put 1 adv}B/rsh{rw cp 2 copy get A 0 eq{pop 128}{A 255 eq{pop 127}{A 2 idiv S 128 and or}ifelse} ifelse put 1 adv}B/clr{rw cp 2 index string putinterval adv}B/set{rw cp fillstr 0 4 index getinterval putinterval adv}B/fillstr 18 string 0 1 17 {2 copy 255 put pop}for N/pl[{adv 1 chg}{adv 1 chg nd}{1 add chg}{1 add chg nd}{adv lsh}{adv lsh nd}{adv rsh}{adv rsh nd}{1 add adv}{/rc X nd}{ 1 add set}{1 add clr}{adv 2 chg}{adv 2 chg nd}{pop nd}]A{bind pop} forall N/D{/cc X A type/stringtype ne{]}if nn/base get cc ctr put nn /BitMaps get S ctr S sf 1 ne{A A length 1 sub A 2 index S get sf div put }if put/ctr ctr 1 add N}B/I{cc 1 add D}B/bop{userdict/bop-hook known{ bop-hook}if/SI save N @rigin 0 0 moveto/V matrix currentmatrix A 1 get A mul exch 0 get A mul add .99 lt{/QV}{/RV}ifelse load def pop pop}N/eop{ SI restore userdict/eop-hook known{eop-hook}if showpage}N/@start{ userdict/start-hook known{start-hook}if pop/VResolution X/Resolution X 1000 div/DVImag X/IEn 256 array N 2 string 0 1 255{IEn S A 360 add 36 4 index cvrs cvn put}for pop 65781.76 div/vsize X 65781.76 div/hsize X}N /p{show}N/RMat[1 0 0 -1 0 0]N/BDot 260 string N/Rx 0 N/Ry 0 N/V{}B/RV/v{ /Ry X/Rx X V}B statusdict begin/product where{pop false[(Display)(NeXT) (LaserWriter 16/600)]{A length product length le{A length product exch 0 exch getinterval eq{pop true exit}if}{pop}ifelse}forall}{false}ifelse end{{gsave TR -.1 .1 TR 1 1 scale Rx Ry false RMat{BDot}imagemask grestore}}{{gsave TR -.1 .1 TR Rx Ry scale 1 1 false RMat{BDot} imagemask grestore}}ifelse B/QV{gsave newpath transform round exch round exch itransform moveto Rx 0 rlineto 0 Ry neg rlineto Rx neg 0 rlineto fill grestore}B/a{moveto}B/delta 0 N/tail{A/delta X 0 rmoveto}B/M{S p delta add tail}B/b{S p tail}B/c{-4 M}B/d{-3 M}B/e{-2 M}B/f{-1 M}B/g{0 M} B/h{1 M}B/i{2 M}B/j{3 M}B/k{4 M}B/w{0 rmoveto}B/l{p -4 w}B/m{p -3 w}B/n{ p -2 w}B/o{p -1 w}B/q{p 1 w}B/r{p 2 w}B/s{p 3 w}B/t{p 4 w}B/x{0 S rmoveto}B/y{3 2 roll p a}B/bos{/SS save N}B/eos{SS restore}B end %%EndProcSet TeXDict begin 40258431 52099146 1000 600 600 (cfitsio.dvi) @start %DVIPSBitmapFont: Fa cmti10 10.95 17 /Fa 17 118 df<49B712C018F818FE903B0003FE0003FF9438007F804BEC1FC0F00FE0F0 07F014074BEC03F8F001FCA2140F4BEC00FEA3141F4B15FFA3143F5DA3027F5D5DA219FE 14FF92C81203A34917FC4A1507A219F813034A150F19F0A20107EE1FE05CF03FC0A2010F EE7F804A16006060011F4B5A4A4A5A4D5AA2013F4B5A4AEC3FC04DC7FC017F15FEEE03FC 4AEB0FF001FFEC7FE0B8128004FCC8FC16E0403E7BBD45>68 D<49B648B6FC495DA2D900 0390C7000313004B5D4B5DA2180714074B5DA2180F140F4B5DA2181F141F4B5DA2183F14 3F4B5DA2187F147F4B5DA218FF91B8FC96C7FCA292C712015B4A5DA2170313034A5DA217 0713074A5DA2170F130F4A5DA2171F131F4A5DA2173F133F4A5DA2017F157FA24A5D496C 4A7EB66CB67EA3483E7BBD44>72 D<001FB500F090B512F0485DA226003FF0C7380FFC00 4AEC03F04A5D715A017F1503A24A5DA201FF150795C7FC91C8FCA2485E170E5BA2000316 1E171C5BA20007163C17385BA2000F167817705BA2001F16F05F5BA2003F1501A2495DA2 007F1503A2495DA2160794C8FC48C8FC5E160E161E6C151C163C5E5E5E6C6C13014B5A00 1F4A5A6C6C011FC9FC6D133E6C6C13F83903FC07F0C6B512C0013F90CAFCEB07F83C406F BD44>85 D<147E49B47E903907C1C38090391F80EFC090383F00FF017E137F4914804848 133F485AA248481400120F5B001F5C157E485AA215FE007F5C90C7FCA21401485C5AA214 03EDF0385AA21407EDE078020F1370127C021F13F0007E013F13E0003E137FECF3E1261F 01E313C03A0F8781E3803A03FF00FF00D800FC133E252977A72E>97 DI101 D103 D<1478EB01FCA21303A314F8EB00E01400AD137C48B4FC38038F80EA0707000E 13C0121E121CEA3C0F1238A2EA781F00701380A2EAF03F140012005B137E13FE5BA21201 5BA212035B1438120713E0000F1378EBC070A214F0EB80E0A2EB81C01383148038078700 EA03FEEA00F8163E79BC1C>105 D108 DIII<903903E001F890390F F807FE903A1E7C1E0F80903A1C3E3C07C0013C137801389038E003E0EB783F017001C013 F0ED80019038F07F0001E015F8147E1603000113FEA2C75AA20101140717F05CA2010314 0F17E05CA20107EC1FC0A24A1480163F010F15005E167E5E131F4B5A6E485A4B5A90393F B80F80DA9C1FC7FCEC0FFCEC03E049C9FCA2137EA213FEA25BA21201A25BA21203A2387F FFE0B5FCA22D3A80A72E>I114 DII<137C48B4 141C26038F80137EEA0707000E7F001E15FE121CD83C0F5C12381501EA781F007001805B A2D8F03F1303140000005D5B017E1307A201FE5C5B150F1201495CA2151F0003EDC1C049 1481A2153F1683EE0380A2ED7F07000102FF13005C01F8EBDF0F00009038079F0E90397C 0F0F1C90391FFC07F8903907F001F02A2979A731>I E %EndDVIPSBitmapFont %DVIPSBitmapFont: Fb cmmi10 10.95 1 /Fb 1 63 df<126012F8B4FCEA7FC0EA1FF0EA07FCEA01FF38007FC0EB1FF0EB07FCEB01 FF9038007FC0EC1FF0EC07FCEC01FF9138007FC0ED1FF0ED07FCED01FF9238007FC0EE1F F0EE07FCEE01FF9338007FC0EF1FF0EF07F8EF01FCA2EF07F8EF1FF0EF7FC0933801FF00 EE07FCEE1FF0EE7FC04B48C7FCED07FCED1FF0ED7FC04A48C8FCEC07FCEC1FF0EC7FC049 48C9FCEB07FCEB1FF0EB7FC04848CAFCEA07FCEA1FF0EA7FC048CBFC12FC1270363678B1 47>62 D E %EndDVIPSBitmapFont %DVIPSBitmapFont: Fc cmsy10 10.95 4 /Fc 4 107 df15 D<153FEC03FFEC0FE0EC3F80EC7E00495A5C495AA2495AB3AA130F5C131F495A91C7FC13 FEEA03F8EA7FE048C8FCEA7FE0EA03F8EA00FE133F806D7E130F801307B3AA6D7EA26D7E 80EB007EEC3F80EC0FE0EC03FFEC003F205B7AC32D>102 D<12FCEAFFC0EA07F0EA01FC EA007E6D7E131F6D7EA26D7EB3AA801303806D7E1300147FEC1FC0EC07FEEC00FFEC07FE EC1FC0EC7F0014FC1301495A5C13075CB3AA495AA2495A133F017EC7FC485AEA07F0EAFF C000FCC8FC205B7AC32D>I<126012F0B3B3B3B3B11260045B76C319>106 D E %EndDVIPSBitmapFont %DVIPSBitmapFont: Fd cmbx12 12 58 /Fd 58 122 df12 D45 DI48 DIII<163FA25E 5E5D5DA25D5D5D5DA25D92B5FCEC01F7EC03E7140715C7EC0F87EC1F07143E147E147C14 F8EB01F0EB03E0130714C0EB0F80EB1F00133E5BA25B485A485A485A120F5B48C7FC123E 5A12FCB91280A5C8000F90C7FCAC027FB61280A531417DC038>I<0007150301E0143F01 FFEB07FF91B6FC5E5E5E5E5E16804BC7FC5D15E092C8FC01C0C9FCAAEC3FF001C1B5FC01 C714C001DF14F09039FFE03FFC9138000FFE01FC6D7E01F06D13804915C0497F6C4815E0 C8FC6F13F0A317F8A4EA0F80EA3FE0487E12FF7FA317F05B5D6C4815E05B007EC74813C0 123E003F4A1380D81FC0491300D80FF0495AD807FEEBFFFC6CB612F0C65D013F1480010F 01FCC7FC010113C02D427BC038>I<4AB47E021F13F0027F13FC49B6FC01079038807F80 90390FFC001FD93FF014C04948137F4948EBFFE048495A5A1400485A120FA248486D13C0 EE7F80EE1E00003F92C7FCA25B127FA2EC07FC91381FFF8000FF017F13E091B512F89039 F9F01FFC9039FBC007FE9039FF8003FF17804A6C13C05B6F13E0A24915F0A317F85BA412 7FA5123FA217F07F121FA2000F4A13E0A26C6C15C06D4913806C018014006C6D485A6C90 38E01FFC6DB55A011F5C010714C0010191C7FC9038003FF02D427BC038>I<121E121F13 FC90B712FEA45A17FC17F817F017E017C0A2481680007EC8EA3F00007C157E5E00785D15 014B5A00F84A5A484A5A5E151FC848C7FC157E5DA24A5A14035D14074A5AA2141F5D143F A2147F5D14FFA25BA35B92C8FCA35BA55BAA6D5A6D5A6D5A2F447AC238>III I65 DIII< BA12F8A485D8001F90C71201EF003F180F180318011800A2197E193EA3191EA21778A285 A405F890C7FCA316011603161F92B5FCA5ED001F160316011600A2F101E01778A2F103C0 A494C7FC1907A21A80A2190FA2191FA2193FF17F0061601807181F4DB5FCBBFC61A44344 7DC34A>II III75 DIII80 D82 DI<003FBA12E0A59026FE000FEB8003D87FE09338003FF049171F90C71607A2 007E1803007C1801A300781800A400F819F8481978A5C81700B3B3A20107B8FCA545437C C24E>IIII<903801FFE0011F13FE017F6D 7E48B612E03A03FE007FF84848EB1FFC6D6D7E486C6D7EA26F7FA36F7F6C5A6C5AEA00F0 90C7FCA40203B5FC91B6FC1307013F13F19038FFFC01000313E0000F1380381FFE00485A 5B127F5B12FF5BA35DA26D5B6C6C5B4B13F0D83FFE013EEBFFC03A1FFF80FC7F0007EBFF F86CECE01FC66CEB8007D90FFCC9FC322F7DAD36>97 DIIIIIII<137C48B4FC4813804813C0A24813E0A56C 13C0A26C13806C1300EA007C90C7FCAAEB7FC0EA7FFFA512037EB3AFB6FCA518467CC520 >I 107 DI<90277F8007FEEC0FFC B590263FFFC090387FFF8092B5D8F001B512E002816E4880913D87F01FFC0FE03FF8913D 8FC00FFE1F801FFC0003D99F009026FF3E007F6C019E6D013C130F02BC5D02F86D496D7E A24A5D4A5DA34A5DB3A7B60081B60003B512FEA5572D7CAC5E>I<90397F8007FEB59038 3FFF8092B512E0028114F8913987F03FFC91388F801F000390399F000FFE6C139E14BC02 F86D7E5CA25CA35CB3A7B60083B512FEA5372D7CAC3E>II<90397FC00FF8B590B57E02C314E002CF14F89139DFC03F FC9139FF001FFE000301FCEB07FF6C496D13804A15C04A6D13E05C7013F0A2EF7FF8A4EF 3FFCACEF7FF8A318F017FFA24C13E06E15C06E5B6E4913806E4913006E495A9139DFC07F FC02CFB512F002C314C002C091C7FCED1FF092C9FCADB67EA536407DAC3E>II<90387F807FB53881FFE002 8313F0028F13F8ED8FFC91389F1FFE000313BE6C13BC14F8A214F0ED0FFC9138E007F8ED 01E092C7FCA35CB3A5B612E0A5272D7DAC2E>I<90391FFC038090B51287000314FF120F 381FF003383FC00049133F48C7121F127E00FE140FA215077EA27F01E090C7FC13FE387F FFF014FF6C14C015F06C14FC6C800003806C15806C7E010F14C0EB003F020313E0140000 F0143FA26C141F150FA27EA26C15C06C141FA26DEB3F8001E0EB7F009038F803FE90B55A 00FC5CD8F03F13E026E007FEC7FC232F7CAD2C>II< D97FC049B4FCB50103B5FCA50003EC000F6C81B3A85EA25EA25E7E6E491380017FD901F7 13FE9138F807E76DB512C7010F1407010313FE9026007FF0EBFC00372E7CAC3E>I IIII E %EndDVIPSBitmapFont %DVIPSBitmapFont: Fe cmtt10 10.95 93 /Fe 93 127 df<121C127FEAFF80B3EA7F00B2123EC7FCA8121C127FA2EAFF80A3EA7F00 A2121C09396DB830>33 D<00101304007C131F00FEEB3F80A26C137FA248133FB2007E14 00007C7F003C131E00101304191C75B830>I<903907C007C0A2496C487EA8011F131FA2 02C05BA3007FB7FCA2B81280A36C16006C5D3A007F807F80A2020090C7FCA9495BA2003F 90B512FE4881B81280A36C1600A22701FC01FCC7FCA300031303A201F85BA76C486C5AA2 29387DB730>I<1438147C14FCA4EB03FF011F13E090B512FC4880000780481580261FFE FD13C09039F0FC3FE0D83FC0131FD87F80EB0FF001001307007E15F800FE14035A1507A3 6CEC03F0A2007F91C7FC138013C0EA3FF0EA1FFE13FF6C13FF6C14E0000114F86C6C7F01 1F7F01037F0100148002FD13C09138FC7FE0151FED0FF015070018EC03F8127E1501B4FC A35AA26CEC03F07E01801307ED0FE0D83FC0131F01F0EB7FC0D81FFEB512806CB612006C 5C6C5CC614F0013F13C0D907FEC7FCEB00FCA5147C143825477BBE30>II II<141E147F14FF5BEB03 FEEB07FCEB0FF0EB1FE0EB3FC0EB7F80EBFF00485A5B12035B485A120F5BA2485AA2123F 5BA2127F90C7FCA412FEAD127FA47F123FA27F121FA26C7EA27F12076C7E7F12017F6C7E EB7F80EB3FC0EB1FE0EB0FF0EB07FCEB03FEEB01FF7F147F141E184771BE30>I<127812 FE7E7F6C7E6C7EEA0FF06C7E6C7E6C7E6C7EEB7F80133F14C0131FEB0FE014F01307A2EB 03F8A214FC1301A214FE1300A4147FAD14FEA4130114FCA2130314F8A2EB07F0A2130F14 E0EB1FC0133F1480137FEBFF00485A485A485A485AEA3FE0485A485A90C7FC5A12781847 78BE30>I<14E0497E497EA60038EC0380007EEC0FC0D8FF83EB3FE001C3137F9038F3F9 FF267FFBFB13C06CB61280000FECFE00000314F86C5C6C6C13C0011F90C7FC017F13C048 B512F04880000F14FE003FECFF80267FFBFB13C026FFF3F913E09038C3F87F0183133FD8 7E03EB0FC00038EC0380000091C7FCA66D5A6D5A23277AAE30>I<143EA2147FAF007FB7 FCA2B81280A36C1600A2C76CC8FCAF143EA229297DAF30>II<007FB612F0A2B712F8A36C15F0A225077B9E30>I<120F EA3FC0EA7FE0A2EAFFF0A4EA7FE0A2EA3FC0EA0F000C0C6E8B30>I<16F01501ED03F8A2 1507A2ED0FF0A2ED1FE0A2ED3FC0A2ED7F80A2EDFF00A24A5AA25D1403A24A5AA24A5AA2 4A5AA24A5AA24A5AA24AC7FCA2495AA25C1303A2495AA2495AA2495AA2495AA2495AA249 C8FCA2485AA25B1203A2485AA2485AA2485AA2485AA2485AA248C9FCA25AA2127CA22547 7BBE30>I<14FE903807FFC0497F013F13F8497F90B57E48EB83FF4848C6138049137F48 48EB3FC04848EB1FE049130F001F15F0491307A24848EB03F8A290C712014815FCA400FE EC00FEAD6C14016C15FCA36D1303003F15F8A26D1307001F15F0A26D130F6C6CEB1FE0A2 6C6CEB3FC06C6CEB7F806D13FF2601FF8313006CEBFFFE6D5B6D5B010F13E06D5BD900FE C7FC273A7CB830>IIIII<000FB6128048 15C05AA316800180C8FCAEEB83FF019F13C090B512F015FC8181D9FE0313809039F0007F C049133F0180EB1FE06CC7120F000E15F0C81207A216F81503A31218127EA2B4FC150716 F048140F6C15E06C141F6DEB3FC06D137F3A3FE001FF80261FFC0F13006CB55A6C5C6C5C 6C14E06C6C1380D90FFCC7FC25397BB730>II<127CB712FC16FEA416FC48C7EA 0FF816F0ED1FE0007CEC3FC0C8EA7F80EDFF00A24A5A4A5A5D14075D140F5D4A5AA24A5A A24AC7FCA25C5C13015CA213035CA213075CA4495AA6131F5CA96D5A6DC8FC273A7CB830 >I<49B4FC011F13F0017F13FC90B57E0003ECFF804815C048010113E03A1FF8003FF049 131FD83FC0EB07F8A24848EB03FC90C71201A56D1303003F15F86D13076C6CEB0FF06C6C EB1FE0D807FCEB7FC03A03FF83FF806C90B512006C6C13FC011F13F0497F90B512FE4880 2607FE0013C0D80FF8EB3FE0D81FE0EB0FF04848EB07F8491303007F15FC90C712014815 FE481400A66C14016C15FC6D1303003F15F86D1307D81FF0EB1FF06D133F3A0FFF01FFE0 6C90B512C06C1580C6ECFE006D5B011F13F0010190C7FC273A7CB830>I<49B4FC010F13 E0013F13F890B57E4880488048010113803A0FFC007FC0D81FF0EB3FE04848131F49EB0F F048481307A290C7EA03F85A4815FC1501A416FEA37E7E6D1303A26C6C13076C6C130F6D 133FD80FFC13FF6CB6FC7E6C14FE6C14F9013FEBE1FC010F138190380060011400ED03F8 A2150716F0150F000F15E0486C131F486CEB3FC0157FEDFF804A1300EC07FE391FF01FFC 90B55A6C5C6C5C6C1480C649C7FCEB3FF0273A7CB830>I<120FEA3FC0EA7FE0A2EAFFF0 A4EA7FE0A2EA3FC0EA0F00C7FCAF120FEA3FC0EA7FE0A2EAFFF0A4EA7FE0A2EA3FC0EA0F 000C276EA630>II<16F01503ED07F8151F157FEDFFF0 14034A13C0021F138091383FFE00ECFFF8495B010713C0495BD93FFEC7FC495A3801FFF0 485B000F13804890C8FCEA7FFC5BEAFFE05B7FEA7FF87FEA1FFF6C7F000313E06C7F3800 7FFC6D7E90380FFF806D7F010113F06D7FEC3FFE91381FFF80020713C06E13F01400ED7F F8151F1507ED03F01500252F7BB230>I<007FB7FCA2B81280A36C16006C5DCBFCA7003F B612FE4881B81280A36C1600A229157DA530>I<1278127EB4FC13C07FEA7FF813FEEA1F FF6C13C000037F6C13F86C6C7EEB1FFF6D7F010313E06D7F9038007FFC6E7E91380FFF80 6E13C0020113F080ED3FF8151F153FEDFFF05C020713C04A138091383FFE004A5A903801 FFF0495B010F13804990C7FCEB7FFC48485A4813E0000F5B4890C8FCEA7FFE13F8EAFFE0 5B90C9FC127E1278252F7BB230>III<147F4A7EA2497FA4497F14F7A401077F14E3A301 0F7FA314C1A2011F7FA490383F80FEA590387F007FA4498049133F90B6FCA34881A39038 FC001F00038149130FA4000781491307A2D87FFFEB7FFFB56CB51280A46C496C13002939 7DB830>I<007FB512F0B612FE6F7E82826C813A03F8001FF815076F7E1501A26F7EA615 015EA24B5A1507ED1FF0ED7FE090B65A5E4BC7FC6F7E16E0829039F8000FF8ED03FC6F7E 1500167FA3EE3F80A6167F1700A25E4B5A1503ED1FFC007FB6FCB75A5E16C05E6C02FCC7 FC29387EB730>I<91387F803C903903FFF03E49EBFC7E011F13FE49EBFFFE5B9038FFE0 7F48EB801F3903FE000F484813075B48481303A2484813015B123F491300A2127F90C8FC 167C16005A5AAC7E7EA2167C6D14FE123FA27F121F6D13016C6C14FCA26C6CEB03F86D13 076C6CEB0FF03901FF801F6C9038E07FE06DB512C06D14806D1400010713FC6D13F09038 007FC0273A7CB830>I<003FB512E04814FCB67E6F7E6C816C813A03F8007FF0ED1FF815 0F6F7E6F7E15016F7EA2EE7F80A2163F17C0161FA4EE0FE0AC161F17C0A3163F1780A216 7F17005E4B5A15034B5A150F4B5AED7FF0003FB65A485DB75A93C7FC6C14FC6C14E02B38 7FB730>I<007FB7FCB81280A47ED803F8C7123FA8EE1F0093C7FCA4157C15FEA490B5FC A6EBF800A4157C92C8FCA5EE07C0EE0FE0A9007FB7FCB8FCA46C16C02B387EB730>I<00 3FB712804816C0B8FCA27E7ED801FCC7121FA8EE0F8093C7FCA5153E157FA490B6FCA690 38FC007FA4153E92C8FCAE383FFFF8487FB5FCA27E6C5B2A387EB730>I<02FF13F00103 EBC0F8010F13F1013F13FD4913FF90B6FC4813C1EC007F4848133F4848131F49130F485A 491307121F5B123F491303A2127F90C7FC6F5A92C8FC5A5AA892B5FC4A14805CA26C7F6C 6D1400ED03F8A27F003F1407A27F121F6D130F120F7F6C6C131FA2D803FE133F6C6C137F ECC1FF6C90B5FC7F6D13FB010F13F30103EBC1F0010090C8FC293A7DB830>I<3B3FFF80 0FFFE0486D4813F0B56C4813F8A26C496C13F06C496C13E0D803F8C7EAFE00B290B6FCA6 01F8C7FCB3A23B3FFF800FFFE0486D4813F0B56C4813F8A26C496C13F06C496C13E02D38 7FB730>I<007FB6FCB71280A46C1500260007F0C7FCB3B3A8007FB6FCB71280A46C1500 213879B730>I<49B512F04914F85BA27F6D14F090C7EAFE00B3B3123C127EB4FCA24A5A 1403EB8007397FF01FF86CB55A5D6C5C00075C000149C7FC38003FF025397AB730>II<383FFFF8487FB57EA26C5B6C5BD801FCC9FCB3B0EE0F80EE1FC0A9003FB7FC5AB8 FCA27E6C16802A387EB730>III<90383FFFE048B512FC000714FF4815804815C04815 E0EBF80001E0133FD87F80EB0FF0A290C71207A44815F8481403B3A96C1407A26C15F0A3 6D130FA26D131F6C6CEB3FE001F813FF90B6FC6C15C06C15806C1500000114FCD8003F13 E0253A7BB830>I<007FB512F0B612FE6F7E16E0826C813903F8003FED0FFCED03FE1501 6F7EA2821780163FA6167F17005EA24B5A1503ED0FFCED3FF890B6FC5E5E16804BC7FC15 F001F8C9FCB0387FFFC0B57EA46C5B29387EB730>I<90383FFFE048B512FC000714FF48 15804815C04815E0EBF80001E0133F4848EB1FF049130F90C71207A44815F8481403B3A8 147E14FE6CEBFF076C15F0EC7F87A2EC3FC7018013CF9038C01FFFD83FE014E0EBF80F90 B6FC6C15C06C15806C1500000114FCD8003F7FEB00016E7EA21680157F16C0153F16E015 1F16F0150FED07E025467BB830>I<003FB57E4814F0B612FC15FF6C816C812603F8017F 9138003FF0151F6F7E15071503821501A515035E1507150F4B5A153F4AB45A90B65A5E93 C7FC5D8182D9F8007FED3FE0151F150F821507A817F8EEF1FCA53A3FFF8003FB4801C0EB FFF8B56C7E17F06C496C13E06C49EB7FC0C9EA1F002E397FB730>I<90390FF803C0D97F FF13E048B512C74814F74814FF5A381FF80F383FE001497E4848137F90C7123F5A48141F A2150FA37EED07C06C91C7FC7F7FEA3FF0EA1FFEEBFFF06C13FF6C14E0000114F86C8001 1F13FF01031480D9003F13C014019138007FE0151FED0FF0A2ED07F8A2007C140312FEA5 6C140716F07F6DEB0FE06D131F01F8EB3FC001FF13FF91B51280160000FD5CD8FC7F13F8 D8F81F5BD878011380253A7BB830>I<003FB712C04816E0B8FCA43AFE003F800FA8007C ED07C0C791C7FCB3B1011FB5FC4980A46D91C7FC2B387EB730>I<3B7FFFC007FFFCB56C 4813FEA46C496C13FCD803F8C7EA3F80B3B16D147F00011600A36C6C14FE6D13016D5CEC 800390393FE00FF890391FF83FF06DB55A6D5C6D5C6D91C7FC9038007FFCEC1FF02F3980 B730>III<3A3FFF01FF F84801837F02C77FA202835B6C01015B3A01FC007F806D91C7FC00005C6D5BEB7F01EC81 FCEB3F8314C3011F5B14E7010F5B14FF6D5BA26D5BA26D5BA26D90C8FCA4497FA2497FA2 815B81EB0FE781EB1FC381EB3F8181EB7F0081497F49800001143F49800003141F498000 07140FD87FFEEB7FFFB590B5128080A25C6C486D130029387DB730>II<001FB612 FC4815FE5AA490C7EA03FCED07F816F0150FED1FE016C0153FED7F80003E1500C85A4A5A 5D14034A5A5D140F4A5A5D143F4A5A92C7FC5C495A5C1303495A5C130F495A5C133F495A 91C8FC5B4848147C4914FE1203485A5B120F485A5B123F485A90B6FCB7FCA46C15FC2738 7CB730>I<007FB5FCB61280A4150048C8FCB3B3B3A5B6FC1580A46C140019476DBE30>I< 127CA212FEA27EA26C7EA26C7EA26C7EA26C7EA26C7EA26C7EA212017FA26C7EA26D7EA2 6D7EA26D7EA26D7EA26D7EA26D7EA2130180A26D7EA26E7EA26E7EA26E7EA26E7EA26E7E A26E7EA2140181A26E7EA2ED7F80A2ED3FC0A2ED1FE0A2ED0FF0A2ED07F8A21503A2ED01 F0150025477BBE30>I<007FB5FCB61280A47EC7123FB3B3B3A5007FB5FCB6FCA46C1400 19477DBE30>I<1307EB1FC0EB7FF0497E000313FE000FEBFF80003F14E0D87FFD13F039 FFF07FF8EBC01FEB800F38FE0003007CEB01F00010EB00401D0E77B730>I<007FB612F0 A2B712F8A36C15F0A225077B7D30>I97 DII<913801FFE04A7F5C A28080EC0007AAEB03FE90381FFF874913E790B6FC5A5A481303380FFC00D81FF0133F49 131F485A150F4848130790C7FCA25AA25AA87E6C140FA27F003F141F6D133F6C7E6D137F 390FF801FF2607FE07EBFFC06CB712E06C16F06C14F76D01C713E0011F010313C0D907FC C8FC2C397DB730>I<49B4FC010713E0011F13F8017F7F90B57E488048018113803A07FC 007FC04848133FD81FE0EB1FE0150F484814F0491307127F90C7FCED03F85A5AB7FCA516 F048C9FC7E7EA27F003FEC01F06DEB03F86C7E6C7E6D1307D807FEEB1FF03A03FFC07FE0 6C90B5FC6C15C0013F14806DEBFE00010713F8010013C0252A7CA830>IIII< 14E0EB03F8A2497EA36D5AA2EB00E091C8FCA9381FFFF8487F5AA27E7EEA0001B3A9003F B612C04815E0B7FCA27E6C15C023397AB830>III<387FFFF8B57EA47EEA0001B3B3A8007FB612F0B712F8A46C15F025387BB7 30>I<02FC137E3B7FC3FF01FF80D8FFEF01877F90B500CF7F15DF92B57E6C010F138726 07FE07EB03F801FC13FE9039F803FC01A201F013F8A301E013F0B3A23C7FFE0FFF07FF80 B548018F13C0A46C486C01071380322881A730>II< 49B4FC010F13E0013F13F8497F90B57E0003ECFF8014013A07FC007FC04848EB3FE0D81F E0EB0FF0A24848EB07F8491303007F15FC90C71201A300FEEC00FEA86C14016C15FCA26D 1303003F15F86D13076D130F6C6CEB1FF06C6CEB3FE06D137F3A07FF01FFC06C90B51280 6C15006C6C13FC6D5B010F13E0010190C7FC272A7CA830>II<49B413F8010FEBC1FC013F13F14913FD48B6FC5A4813 81390FFC007F49131F4848130F491307485A491303127F90C7FC15015A5AA77E7E15037F A26C6C1307150F6C6C131F6C6C133F01FC137F3907FF01FF6C90B5FC6C14FD6C14F9013F 13F1010F13C1903803FE0190C7FCAD92B512F84A14FCA46E14F82E3C7DA730>II<90381FFC1E48B5129F000714FF5A5A5A387FF007EB800100FEC7FC4880A46C143E 007F91C7FC13E06CB4FC6C13FC6CEBFF806C14E0000114F86C6C7F01037F9038000FFF02 001380007C147F00FEEC1FC0A2150F7EA27F151F6DEB3F806D137F9039FC03FF0090B6FC 5D5D00FC14F0D8F83F13C026780FFEC7FC222A79A830>III<3B3F FFC07FFF80486DB512C0B515E0A26C16C06C496C13803B01F80003F000A26D130700005D A26D130F017E5CA2017F131F6D5CA2EC803F011F91C7FCA26E5A010F137EA2ECE0FE0107 5BA214F101035BA3903801FBF0A314FF6D5BA36E5A6E5A2B277EA630>I<3B3FFFC01FFF E0486D4813F0B515F8A26C16F06C496C13E0D807E0C7EA3F00A26D5C0003157EA56D14FE 00015DEC0F80EC1FC0EC3FE0A33A00FC7FF1F8A2147DA2ECFDF9017C5C14F8A3017E13FB A290393FF07FE0A3ECE03FA2011F5C90390F800F802D277FA630>I<3A3FFF81FFFC4801 C37FB580A26C5D6C01815BC648C66CC7FC137FEC80FE90383F81FC90381FC3F8EB0FE3EC E7F06DB45A6D5B7F6D5B92C8FC147E147F5C497F81903803F7E0EB07E790380FE3F0ECC1 F890381F81FC90383F80FE90387F007E017E137F01FE6D7E48486D7E267FFF80B5FCB500 C1148014E3A214C16C0180140029277DA630>I<3B3FFFC07FFF80486DB512C0B515E0A2 6C16C06C496C13803B01FC0003F000A2000014076D5C137E150F017F5C7F151FD91F805B A214C0010F49C7FCA214E00107137EA2EB03F0157C15FCEB01F85DA2EB00F9ECFDF0147D 147FA26E5AA36E5AA35DA2143F92C8FCA25C147EA2000F13FE486C5AEA3FC1EBC3F81387 EB8FF0EBFFE06C5B5C6C90C9FC6C5AEA01F02B3C7EA630>I<001FB612FC4815FE5AA316 FC90C7EA0FF8ED1FF0ED3FE0ED7FC0EDFF80003E491300C7485A4A5A4A5A4A5A4A5A4A5A 4A5A4990C7FC495A495A495A495A495A495A4948133E4890C7127F485A485A485A485A48 5A48B7FCB8FCA46C15FE28277DA630>II< 127CA212FEB3B3B3AD127CA207476CBE30>II<017C13 3848B4137C48EB80FE4813C14813C348EBEFFC397FEFFFF0D8FF8713E0010713C0486C13 80D87C0113003838007C1F0C78B730>I E %EndDVIPSBitmapFont %DVIPSBitmapFont: Ff cmbx12 14.4 62 /Ff 62 123 df<922601FFFC903801FFE0033F9026FF801F13F84AB6D8E07F13FE020F03 F9B6FC023FD9C00FB500C0138091277FFC0003D9FE0113C0902601FFE049495A49494949 4813E04990C714F049484A13E0495A19C0495A7413C0017F17804A6E6E1380719138007E 007192C7FCAEBCFCA526007FF8C7000301C0C8FCB3B3A7007FB5D8F803B612F0A553547D D34E>11 DI<151E153E157E15FCEC01F8EC07F0EC0FE0EC1FC01580143FEC7F00 14FE1301495A5C1307495AA2495A133F5C137FA2495AA24890C7FCA25A5BA21207A2485A A3121F5BA3123FA25BA3127FA55B12FFB3A3127F7FA5123FA37FA2121FA37F120FA36C7E A21203A27F7EA26C7FA26D7EA2133F80131F6D7EA26D7E1303806D7E1300147FEC3F8014 1F15C0EC0FE0EC07F0EC01F8EC00FC157E153E151E1F7973D934>40 D<127012F8127C127E7EEA1FC06C7E6C7E12037F6C7E6C7E7F6D7E133F806D7EA26D7E80 130780A26D7EA26D7EA215807FA215C0A2EC7FE0A315F0143FA315F8A2141FA315FCA514 0F15FEB3A315FC141FA515F8A3143FA215F0A3147F15E0A3ECFFC0A21580A25B1500A249 5AA2495AA25C130F5C495AA2495A5C137F49C7FC5B485A485A5B1207485A485A48C8FC12 7E127C5A12701F7979D934>I45 DII<913803FFC0023F13 FC91B6FC010315C0010F018113F0903A1FFC003FF849486D7E49486D7E49486D7E48496D 138048496D13C0A24817E04890C813F0A34817F8A24817FC49157FA3007F17FEA600FF17 FFB3A5007F17FEA6003F17FCA26D15FFA26C17F8A36C17F0A26C6D4913E0A26C6D4913C0 6C17806E5B6C6D4913006D6C495AD91FFCEB3FF8903A0FFF81FFF06D90B55A01011580D9 003F01FCC7FC020313C0384F7BCD43>I<157815FC14031407141F14FF130F0007B5FCB6 FCA2147F13F0EAF800C7FCB3B3B3A6007FB712FEA52F4E76CD43>II<91380FFFC091B512FC0107ECFF80011F15E090263FF8077F9026FF8001 13FC4848C76C7ED803F86E7E491680D807FC8048B416C080486D15E0A4805CA36C17C06C 5B6C90C75AD801FC1680C9FC4C13005FA24C5A4B5B4B5B4B13C04B5BDBFFFEC7FC91B512 F816E016FCEEFF80DA000713E0030113F89238007FFE707E7013807013C018E07013F0A2 18F8A27013FCA218FEA2EA03E0EA0FF8487E487E487EB57EA318FCA25E18F891C7FC6C17 F0495C6C4816E001F04A13C06C484A1380D80FF84A13006CB44A5A6CD9F0075BC690B612 F06D5D011F1580010302FCC7FCD9001F1380374F7ACD43>I<177C17FEA2160116031607 160FA2161F163F167FA216FF5D5DA25D5DED1FBFED3F3F153E157C15FCEC01F815F0EC03 E01407EC0FC01580EC1F005C147E147C5C1301495A495A5C495A131F49C7FC133E5B13FC 485A5B485A1207485A485A90C8FC123E127E5ABA12C0A5C96C48C7FCAF020FB712C0A53A 4F7CCE43>III<121F7F7FEBFF8091B81280A45A19 00606060A2606060485F0180C86CC7FC007EC95A4C5A007C4B5A5F4C5A160F4C5A484B5A 4C5A94C8FC16FEC812014B5A5E4B5A150F4B5AA24B5AA24B5A15FFA24A90C9FCA25C5D14 07A2140FA25D141FA2143FA4147F5DA314FFA55BAC6D5BA2EC3FC06E5A395279D043>I< 913807FFC0027F13FC0103B67E010F15E090261FFC0113F8903A3FE0003FFCD97F80EB0F FE49C76C7E48488048486E1380000717C04980120F18E0177FA2121F7FA27F7F6E14FF02 E015C014F802FE4913806C7FDBC00313009238F007FE6C02F85B9238FE1FF86C9138FFBF F06CEDFFE017806C4BC7FC6D806D81010F15E06D81010115FC010781011F81491680EBFF E748018115C048D9007F14E04848011F14F048487F48481303030014F8484880161F4848 020713FC1601824848157F173FA2171FA2170FA218F8A27F007F17F06D151FA26C6CED3F E0001F17C06D157F6C6CEDFF806C6C6C010313006C01E0EB0FFE6C01FCEBFFFC6C6CB612 F06D5D010F1580010102FCC7FCD9000F13C0364F7ACD43>I<91380FFF8091B512F80103 14FE010F6E7E4901037F90267FF8007F4948EB3FF048496D7E484980486F7E4849808248 17805A91C714C05A7013E0A218F0B5FCA318F8A618FCA46C5DA37EA25E6C7F6C5DA26C5D 6C7F6C6D137B6C6D13F390387FF803011FB512E36D14C30103028313F89039007FFE03EC 00401500A218F05EA3D801F816E0487E486C16C0487E486D491380A218005E5F4C5A91C7 FC6C484A5A494A5A49495B6C48495BD803FC010F5B9027FF807FFEC7FC6C90B55A6C6C14 F06D14C0010F49C8FC010013F0364F7ACD43>I<171F4D7E4D7EA24D7EA34C7FA24C7FA3 4C7FA34C7FA24C7FA34C8083047F80167E8304FE804C7E03018116F8830303814C7E0307 8116E083030F814C7E031F81168083033F8293C77E4B82157E8403FE824B800201835D84 0203834B800207835D844AB87EA24A83A3DA3F80C88092C97E4A84A2027E8202FE844A82 010185A24A820103854A82010785A24A82010F855C011F717FEBFFFCB600F8020FB712E0 A55B547BD366>65 DI<9326 01FFFCEC01C0047FD9FFC013030307B600F81307033F03FE131F92B8EA803F0203DAE003 EBC07F020F01FCC7383FF0FF023F01E0EC0FF94A01800203B5FC494848C9FC4901F88249 49824949824949824949824990CA7E494883A2484983485B1B7F485B481A3FA24849181F A3485B1B0FA25AA298C7FC5CA2B5FCAE7EA280A2F307C07EA36C7FA21B0F6C6D1980A26C 1A1F6C7F1C006C6D606C6D187EA26D6C606D6D4C5A6D6D16036D6D4C5A6D6D4C5A6D01FC 4C5A6D6DEE7F806D6C6C6C4BC7FC6E01E0EC07FE020F01FEEC1FF80203903AFFE001FFF0 020091B612C0033F93C8FC030715FCDB007F14E0040101FCC9FC525479D261>IIII<932601FFFCEC01C0047FD9FFC013030307B600F81307033F03FE131F92B8 EA803F0203DAE003EBC07F020F01FCC7383FF0FF023F01E0EC0FF94A01800203B5FC4948 48C9FC4901F8824949824949824949824949824990CA7E494883A2484983485B1B7F485B 481A3FA24849181FA3485B1B0FA25AA298C8FC5CA2B5FCAE6C057FB712E0A280A36C94C7 003FEBC000A36C7FA36C7FA27E6C7FA26C7F6C7FA26D7E6D7F6D7F6D6D5E6D7F6D01FC93 B5FC6D13FF6D6C6D5C6E01F0EC07FB020F01FEEC1FF10203903AFFF001FFE0020091B6EA C07F033FEE001F030703FC1307DB007F02E01301040149CAFC5B5479D26A>III75 DIII<93380FFFC00303B6FC031F15E092B712FC 0203D9FC0013FF020F01C0010F13C0023F90C7000313F0DA7FFC02007F494848ED7FFE49 01E0ED1FFF49496F7F49496F7F4990C96C7F49854948707F4948707FA24849717E48864A 83481B804A83481BC0A2481BE04A83A2481BF0A348497113F8A5B51AFCAF6C1BF86E5FA4 6C1BF0A26E5F6C1BE0A36C6D4D13C0A26C6D4D1380A26C1B006C6D4D5A6E5E6C626D6C4C 5B6D6D4B5B6D6D4B5B6D6D4B5B6D6D4B5B6D6D4B90C7FC6D6D4B5A6D01FF02035B023F01 E0011F13F0020F01FC90B512C0020390B7C8FC020016FC031F15E0030392C9FCDB001F13 E0565479D265>II82 D<91260FFF80130791B500F85B010702FF5B011FEDC03F49EDF07F9026FFFC006D5A4801 E0EB0FFD4801800101B5FC4848C87E48488149150F001F824981123F4981007F82A28412 FF84A27FA26D82A27F7F6D93C7FC14C06C13F014FF15F86CECFF8016FC6CEDFFC017F06C 16FC6C16FF6C17C06C836C836D826D82010F821303010082021F16801400030F15C0ED00 7F040714E01600173F050F13F08383A200788200F882A3187FA27EA219E07EA26CEFFFC0 A27F6D4B13806D17006D5D01FC4B5A01FF4B5A02C04A5A02F8EC7FF0903B1FFFC003FFE0 486C90B65AD8FC0393C7FC48C66C14FC48010F14F048D9007F90C8FC3C5479D24B>I<00 3FBC1280A59126C0003F9038C0007F49C71607D87FF8060113C001E08449197F49193F90 C8171FA2007E1A0FA3007C1A07A500FC1BE0481A03A6C994C7FCB3B3AC91B912F0A55351 7BD05E>IIII97 DI<913801FFF8021FEBFF8091B612F0010315FC01 0F9038C00FFE903A1FFE0001FFD97FFC491380D9FFF05B4817C048495B5C5A485BA2486F 138091C7FC486F1300705A4892C8FC5BA312FFAD127F7FA27EA2EF03E06C7F17076C6D15 C07E6E140F6CEE1F806C6DEC3F006C6D147ED97FFE5C6D6CEB03F8010F9038E01FF00103 90B55A01001580023F49C7FC020113E033387CB63C>I<4DB47E0407B5FCA5EE001F1707 B3A4913801FFE0021F13FC91B6FC010315C7010F9038E03FE74990380007F7D97FFC0101 B5FC49487F4849143F484980485B83485B5A91C8FC5AA3485AA412FFAC127FA36C7EA37E A26C7F5F6C6D5C7E6C6D5C6C6D49B5FC6D6C4914E0D93FFED90FEFEBFF80903A0FFFC07F CF6D90B5128F0101ECFE0FD9003F13F8020301C049C7FC41547CD24B>I<913803FFC002 3F13FC49B6FC010715C04901817F903A3FFC007FF849486D7E49486D7E4849130F48496D 7E48178048497F18C0488191C7FC4817E0A248815B18F0A212FFA490B8FCA318E049CAFC A6127FA27F7EA218E06CEE01F06E14037E6C6DEC07E0A26C6DEC0FC06C6D141F6C6DEC3F 806D6CECFF00D91FFEEB03FE903A0FFFC03FF8010390B55A010015C0021F49C7FC020113 F034387CB63D>IIII<137F497E000313E0487FA2487FA76C5BA26C5BC613806DC7FC90C8FC ADEB3FF0B5FCA512017EB3B3A6B612E0A51B547BD325>I107 DIII<913801FFE0021F13FE 91B612C0010315F0010F9038807FFC903A1FFC000FFED97FF86D6C7E49486D7F48496D7F 48496D7F4A147F48834890C86C7EA24883A248486F7EA3007F1880A400FF18C0AC007F18 80A3003F18006D5DA26C5FA26C5F6E147F6C5F6C6D4A5A6C6D495B6C6D495B6D6C495BD9 3FFE011F90C7FC903A0FFF807FFC6D90B55A010015C0023F91C8FC020113E03A387CB643 >I<903A3FF001FFE0B5010F13FE033FEBFFC092B612F002F301017F913AF7F8007FFE00 03D9FFE0EB1FFFC602806D7F92C76C7F4A824A6E7F4A6E7FA2717FA285187F85A4721380 AC1A0060A36118FFA2615F616E4A5BA26E4A5B6E4A5B6F495B6F4990C7FC03F0EBFFFC91 26FBFE075B02F8B612E06F1480031F01FCC8FC030313C092CBFCB1B612F8A5414D7BB54B >I<90397FE003FEB590380FFF80033F13E04B13F09238FE1FF89139E1F83FFC0003D9E3 E013FEC6ECC07FECE78014EF150014EE02FEEB3FFC5CEE1FF8EE0FF04A90C7FCA55CB3AA B612FCA52F367CB537>114 D<903903FFF00F013FEBFE1F90B7FC120348EB003FD80FF8 1307D81FE0130148487F4980127F90C87EA24881A27FA27F01F091C7FC13FCEBFFC06C13 FF15F86C14FF16C06C15F06C816C816C81C681013F1580010F15C01300020714E0EC003F 030713F015010078EC007F00F8153F161F7E160FA27E17E07E6D141F17C07F6DEC3F8001 F8EC7F0001FEEB01FE9039FFC00FFC6DB55AD8FC1F14E0D8F807148048C601F8C7FC2C38 7CB635>I<143EA6147EA414FEA21301A313031307A2130F131F133F13FF5A000F90B6FC B8FCA426003FFEC8FCB3A9EE07C0AB011FEC0F8080A26DEC1F0015806DEBC03E6DEBF0FC 6DEBFFF86D6C5B021F5B020313802A4D7ECB34>IIII<007FB500F090387FFFFEA5C66C48C7000F90C7FC6D6CEC07F86D6D5C 6D6D495A6D4B5A6F495A6D6D91C8FC6D6D137E6D6D5B91387FFE014C5A6E6C485A6EEB8F E06EEBCFC06EEBFF806E91C9FCA26E5B6E5B6F7E6F7EA26F7F834B7F4B7F92B5FCDA01FD 7F03F87F4A486C7E4A486C7E020F7FDA1FC0804A486C7F4A486C7F02FE6D7F4A6D7F495A 49486D7F01076F7E49486E7E49486E7FEBFFF0B500FE49B612C0A542357EB447>II<001FB8FC1880A3912680007F130001FCC7B5FC01F0495B495D49 495B495B4B5B48C75C5D4B5B5F003E4A90C7FC92B5FC4A5B5E4A5B5CC7485B5E4A5B5C4A 5B93C8FC91B5FC495B5D4949EB0F805B495B5D495B49151F4949140092C7FC495A485E48 5B5C485E485B4A5C48495B4815074849495A91C712FFB8FCA37E31357CB43C>I E %EndDVIPSBitmapFont %DVIPSBitmapFont: Fg cmbx12 20.74 23 /Fg 23 121 df48 DI<9238 0FFFE04AB67E020F15F0027F15FE49B87E4917E0010F17F8013F8349D9C01F14FF9027FF FC0001814801E06D6C80480180021F804890C86C8048486F8048486F8001FF6F804801C0 6E8002F081486D18806E816E18C0B5821BE06E81A37214F0A56C5BA36C5B6C5B6C5B0003 13C0C690C9FC90CA15E060A34E14C0A21B80601B0060626295B55A5F624D5C624D5C4D91 C7FC614D5B4D13F04D5B6194B55A4C49C8FC4C5B4C5B4C13E04C5B604C90C9FCEE7FFC4C 5A4B5B4B5B4B0180EC0FF04B90C8FC4B5A4B5A4B48ED1FE0EDFFE04A5B4A5B4A90C9FC4A 48163F4A5ADA3FF017C05D4A48167F4A5A4990CA12FFD903FC160749BAFC5B4919805B5B 90BBFC5A5A5A5A481A005A5ABCFCA462A44C7176F061>I<923801FFFE033FEBFFF84AB7 FC020F16E0023F16F84A16FE49B97E49DA003F80010F01F0010714F04901800101804948 C880D97FF86F7F02E081496C834801FC6F148014FF486E6E14C08181481AE081A96C5C1B C06C4A5C6C5C6D90C815806D5AD90FF85D90CA150062606295B55A4D5C624D5C4D5C4D91 C7FC4D13FC4D5B4CB512E0047F1480037FB548C8FC92B612F818C018F8F0FF806F15F092 C7003F13FC050713FF050114C071807213F8727F727F867214801BC07214E01BF0A27214 F81BFCA37214FEA31BFFEBFF80000313E0487F001F13FC487FA2487FA2B67EA31BFEA360 1BFCA292C8FC6C1AF84A5D4A18F06C494B14E05C6C01C04B14C06C90C915804E14006C6D 4B5B6C01F092B55A6C01FC4A5C27007FFFC001075C6D01FE013F14C0010F90B85A6D4DC7 FC010117F8D9003F16E0020F93C8FC020015F0030749C9FC507378F061>II<0170187001FEEF01F86D6C160F02F8167FDAFF80 EC07FF03FE49B5FC92B85A6262A26297C7FC61616119E061614EC8FC18F86018C095C9FC 17F817C0020701F8CAFC91CDFCB0923801FFFC031FEBFFE092B612FC020315FF020F16C0 4A16F0027FD9003F7FDAFFF0010F13FE038001037F4AC76C8002F86E804A6F7F4A6F7F4A 834A6F7F91C980137E017C707F90CAFC1B80A21BC0A2841BE0A51BF0A313FE3803FF8000 0F7F4813F0487F5A80B5FCA41BE0A44E14C05C7E4A18805C4A5D6C90C9150001E0606C6C 5E6D606C6C4C5B7F000794B55A6C6C6C4A5C6C6D4A5C6E4A5C26007FF8021F49C7FC6DB4 027F5B6DD9F007B55A6D90B712E0010317806D4CC8FC6D6C15F8021F15C002034AC9FCDA 003F13804C7376F061>I<94381FFF800403B512F8043F14FE4BB77E030782031F16F003 7F8292B5D8FC017F02039139C0001FFE4A49C7EA07FF021F01F8804A496E13804A01C014 0F91B548023F13C04991C85A494992B5FC49494A14E0495B495E5D5B495BA290B55A5A5D 487114C0A24891C91480731300735A48F00FF896C8FC485BA45AA44849903803FFE0041F 13FE047FEBFFC04BB612F84B81030F15FFB590261FF8038092273FE0007F13E00480011F 7F4BC76C7F03FE6E7F4B6E7FDAFDF86E7FDAFFF017804B6E14C01BE05D7313F05D1BF8A2 92C914FC85A21BFE5CA31BFFA26C5BA87EA4807EA21BFE7EA37E1BFC6E5E6C1AF8A27E6F 17F06C95B512E06D7F1BC06D6D4A14806D4C1400816D6D4A5B6D6D4A5B6D01FF4A13F001 006E017F5B6ED9F007B55A6E90B7C7FC020F5E020316F86E16E0DA003F1580030702FCC8 FCDB007F1380507378F061>II<93B57E031F14FC92B77E020316F0020F16FC023F16FF4A8349B5D8 800314E04901F8C7003F7F4901C0020F7F4990C800037FD91FFC6F7F49486F6C7E137F4A 7013804948827313C05A4A821BE05AA285487FA38080806E5E8003C017C08103F85D03FE 17806F6C5C6C6F160004F05C04FC4A5A6C6F5D706C13FFDDE0015B6CDCF8035BDDFC0F13 C06DDBFF1F5B6D93B5C7FC19FC6D17F06D5F6D17806D17E06D836D6C16FC6E16FF020F83 6E17E06E83020F83023F8391B97E4984010701F0178049D9C07F16C0013FD9801F16E049 EB00074948010116F048497F4849023F15F84849140F4A6E15FC48160148496E6C14FE4A 151F488391C9120348050014FF193F49838500FF84854983A28586A3861BFEA27FA2007F 1AFC7F1A7F1BF86C7FF2FFF06C7F6E4C13E06C6D4C13C06C6D5E6E4C13806C6D4C13006C 6D6CED7FFE6C02E04A485A013F01FC020F13F06D9026FFC001B55A010791B712806D95C7 FC010017FC021F16F002071680DA007F02FCC8FC030191C9FC507378F061>I<93B5FC03 1F14F092B612FE02076F7E021F16E04A16F891B87E49DAF00713FF0107DA0001804901FC 6D6C7F49496E7F49496E7F49496E7F90B5486E7F484A8048854891C86C7FA2487114805C 481AC0A2487213E0A2484918F0A31BF8A2B5FCA27313FCA51BFEA71BFF61A27EA396B6FC 7EA2806C5FA27E606C7F607E6C6E5C6CEF1FBF6D6DEC3F3F6D6D147F6D6D14FE6D6DEB01 FC6D01FE130701019039FFC01FF86D91B500F014FE023F15C06E15800203ECFE00DA007F 13F8030713C092C9FC4F13FCA41BF8A31BF0D91FF093B5FCEB7FFC496C18E0487F486E17 C06048801B804E1400A26260624E5B4B5C626C91C8485B4A4B5B4A92B55A6C01F04A91C7 FC02804A5B6C01E0020F5B6D6C023F13F002FE91B55A90273FFFE00F5C6D90B7C8FC0107 16FC6D16F0010016C0023F92C9FC020714F09126007FFECAFC507378F061>I65 DI<96267FFFE01670063FB6ED01F80503B700F01403053F04FC14074CB96C130F040706 E0131F043F72133F93BA00FC137F0303DC00076D13FF030F03C09039003FFF814B02FCC8 000713C3037F02E0030113F792B600806F6CB5FC02034ACA121F4A02F8834A02E0834A4A 1701027F4A8391B548CC7E494A85495C4C854988494A85494A85495C8A4991CDFC90B548 86A2484A1B7FA2481E3F5D481E1F5D5A1F0FA2485CA3481E075DA2F703F0489BC7FCA45D A2B6FCB27EA281A47EA2F703F06FF307F87EA36C80A21F0F7E6F1CF07E6F1B1F7E20E06C 6E1B3F816DF57FC06D80F7FF806D806D6E4F13006D6E616D525A826D6E4F5A6D6E4F5A6E 6D6C4E5A021F6EF0FFE06E6E4D5B6E02F84D5B6E02FE050F90C7FC02006E6CEE3FFE6F02 F0EEFFFC031F02FE03035B6FDAFFC0021F13E0030303FF0103B55A030093B7C8FC043F18 FC040718F0040118C0DC003F94C9FC050316F8DD003F1580DE007F01F0CAFC757A75F78C >I<92383FFFF80207B612E0027F15FC49B87E010717E0011F83499026F0007F13FC4948 C7000F7F90B502036D7E486E6D806F6D80727F486E6E7F8486727FA28684A26C5C72806C 5C6D90C8FC6D5AEB0FF8EB03E090CAFCA70507B6FC041FB7FC0303B8FC157F0203B9FC02 1FECFE0391B612800103ECF800010F14C04991C7FC017F13FC90B512F04814C0485C4891 C8FC485B5A485B5C5A5CA2B5FC5CA360A36E5DA26C5F6E5D187E6C6D846E4A48806C6D4A 4814FC6C6ED90FF0ECFFFC6C02E090263FE07F14FE00019139FC03FFC06C91B6487E013F 4B487E010F4B1307010303F01301D9003F0280D9003F13FC020101F8CBFC57507ACE5E> 97 D<97380FFFE00607B6FCA8F00003190086B3AD93383FFF800307B512F8033F14FF4A B712C0020716F0021F16FC027F9039FE007FFE91B500F0EB0FFF01030280010190B5FC49 49C87E49498149498149498149498190B548814884484A8192CAFC5AA2485BA25A5C5AA3 5A5CA4B5FCAF7EA4807EA37EA2807EA26C7F616C6E5D6C606C80616D6D5D6D6D5D6D6D92 B67E6D6D4A15FC010301FF0207EDFFFE6D02C0EB3FFE6D6C9039FC01FFF86E90B65A020F 16C002031600DA007F14FC030F14E09226007FFEC749C7FC5F797AF76C>100 D<93387FFF80030FB512FC037FECFF804AB712E0020716F8021F16FE027FD9F8077F49B5 D8C000804991C7003F13E04901FC020F7F49496E7F49498049496E7F49496E7F90B55A48 727E92C914804884485B1BC048841BE0485BA27313F05AA25C5AA21BF885A2B5FCA391BA FCA41BF002F8CCFCA67EA3807EA47E806CF103F0F207F86C7F1A0F6C6E17F06C191F6F17 E06C6E163F6D6DEE7FC06D6D16FF6D6D4B13806D6D4B13006D6D6CEC0FFE6D02E0EC3FFC 6D02F8ECFFF86D9126FFC00F5B023F91B65A020F178002034CC7FC020016F8031F15E003 0392C8FCDB000F13E04D507BCE58>I<903801FFFCB6FCA8C67E131F7FB3AD95380FFFE0 95B512FE05036E7E050F15E0053F15F84D81932701FFF01F7F4CD900077FDC07FC6D80DC 0FF06D80DC1FC07F4C48824CC8FC047E6F7F5EEDFDF85E03FF707F5EA25EA25EA293C9FC A45DB3B3A6B8D8E003B81280A8617879F76C>104 DI<902601FFF891380F FFE0B692B512FE05036E7E050F15E0053F15F84D81932701FFF01F7F4CD900077FDC07FC 6D80C66CDA0FF06D80011FDA1FC07F6D4A48824CC8FC047E6F7F5EEDF9F85E03FB707F5E 15FF5EA25EA293C9FCA45DB3B3A6B8D8E003B81280A8614E79CD6C>110 D<902601FFFCEC7FFEB6020FB512F0057F14FE4CB712C0040716F0041F82047F16FE93B5 C66C7F92B500F0010F14C0C66C0380010380011F4AC76C806D4A6E8004F06F7F4C6F7F4C 6F7F4C8193C915804B7014C0861DE0A27414F0A27414F8A47513FCA57513FEAF5113FCA5 98B512F8A31DF0621DE0621DC0621D806F5E701800704B5B505B704B5B7092B55A04FC4A 5C704A5C706C010F5C05E0013F49C7FC9227FE7FFC01B55A70B712F0040F16C0040393C8 FC040015F8053F14C0050301F0C9FC94CCFCB3A6B812E0A85F6F7ACD6C>112 D<902601FFF8EB07FEB691383FFFC094B512F00403804C14FE4C8093261FFC3F13809326 3FE07F13C0DC7F80B5FCC66C5D011FDAFE0114E06DEBF9FC16F815FB16F016E015FF16C0 7114C05E72138095381FFE0093C76C5AF001E095C8FCA25DA65DB3B3A2B812F8A8434E7A CD4F>114 D<15FFA75CA55CA45CA25CA25CA25CA25C91B5FCA25B5B5B131F5B90B9FC12 0FBAFCA6D8000791C9FCB3B3A3F01FE0AE183F7014C07F187F7014806D16FF826D4B1300 6E6D485AEEFE0F6E90B55A020F5D6E5D020115C06E6C5C031F49C7FC030113F03B6E7CEC 4B>116 D<007FB7023FB612F0A8D8000302C0020191C7FC6D6E9138007FF0705E6D4E5A 6E6D4A5B6E6D4A90C8FC6E6D5C704A5A6E4C5A6E6E5C6E6E495A6E6E495A7113FF6E6E48 5B6F4A5B6F6D4890C9FC6F01FE5B71485A6FEC9FF86F14BF6FECFFF06F5D616F5D7091CA FC705B828470808270807080854C805E4C80854C804C81EE7FE7DCFFE3804B01C1804B01 80804D804B487F4B486D7F031F6E7F4B486D7F4B48824B487F4C6D804A496D804A90C880 4A844A48814A486F7F4A486F7F4B6F7F4A48844A486F80010F01F881B76C91B712FEA85F 4D7DCC66>120 D E %EndDVIPSBitmapFont %DVIPSBitmapFont: Fh cmsl10 10.95 39 /Fh 39 91 df<1530157015E0EC03C0EC0780EC0F00141E5C147C5C5C495A1303495A5C 130F49C7FCA2133E137E137C13FC5B1201A2485AA25B1207A2485AA3485AA448C8FCA45A 127EA512FE5AA95AA87EA2127CA5123C123EA2121EA2121F7EA26C7EA26C7EA26C7E1200 13707FA213181C5A74C323>40 D<497E806D7E1470147880A280A280A2EC0780A215C014 03A215E0A3EC01F0A615F8AF140315F0A5140715E0A4140F15C0A3141F1580A3EC3F00A2 143E147EA2147C14FC5C13015C13035C13075C495AA249C7FC131E133E5B13785B485A48 5A12075B000EC8FC5A5A12F05A1D5A7FC323>I<007FB5FCA2B512FEA418067C961E>45 D<121EEA3F80EA7FC012FFA41380EA7F00123C0A0A788919>I<1703EF0780170FA2EF1F 00A2173EA25FA25FA24C5AA24C5AA24C5AA24C5AA24CC7FCA2163E167E167C5EA24B5AA2 4B5AA24B5AA24B5AA24BC8FCA2153EA25DA25DA24A5AA24A5AA24A5AA24A5AA24AC9FCA2 143EA25CA25CA2495AA2495AA2495AA2495A131F91CAFC133EA25BA25BA2485AA2485AA2 485AA2485AA248CBFCA2123EA25AA25AA21270315B7FC32D>II<157015F01401 1407143F903803FFE0137FEBFFCFEBF80F1300141F15C0A5143F1580A5147F1500A55C5C A513015CA513035CA513075CA5130F5CA3131F497EB612F8A31D3D78BC2D>III<161C163C167CA216FCED01F815031507150FA2151DED3BF0 157315E315C31401EC038391380707E0140E141CA2143814709138E00FC0EB01C0148013 03EB0700130E49EB1F805B133013705B485A4848EB3F0090C7FC5A120E5A5A48147E1260 B8FCA3C73801FE00A25DA41403A25DA314074A7E0107B512F8A3283E7BBD2D>I<010614 03D90780131F90390FF801FE91B512FC16F816F016E0168049EBFE0015F890381C7FC091 C8FCA3133C1338A513781370A2EC1FE0ECFFF8903873E03E9038FF001F01FCEB0F804914 C049EB07E04914F049130390C7FC16F8A61507A21206EA3F80487EA2150F00FF15F0A249 14E090C7121F00FC15C000F0143F00701580ED7F0012786C14FE4A5A6C495A390F800FE0 3907E03FC06CB5C7FCC613FCEB1FE0283F7ABC2D>IIIII<17E016011603831607A2160FA2161F83163FA2167F167716F7EEE7FCED01E316 C3150316831507EE03FEED0F01150E151E151C153C03387FED7800157015F05D4A488017 7F4A5AA24AC7FCA2020E81173F5C021FB6FC5CA20270C7EA3FE0171F5CA2495AA2494881 170F49C8FCA2130EA24982013C1507A2137CD801FE4B7E2607FF80EC3FFEB500F00107B5 12FC19F85E3E417DC044>65 D<013FB7FC18E018FC903B007FE00007FE6E48903801FF80 9438007FC05DF03FE0F01FF0A3027F16F892C8FCA54A16F04A153F19E0187F19C0F0FF80 01014B13004A4A5A4D5AEF1FF04D5ADC03FFC7FC49B612F8EFFF8002F8C7EA3FE0EF0FF0 EF07FC717E010715014A81711380A319C0130F5CA5011F4B13805C19005F601707013F4B 5A4A4A5A4D5A4D5A017F913801FF8001FF020F90C7FCB812FC17F094C8FC3D3E7DBD40> II<013FB7FC18E018F8903B007FF0 000FFE6E48EB01FF9438007FC04B6E7E180F85727E727E147F4B6E7EA2727EA302FF1780 92C9FCA54918C05CA41A8013034A5DA41A0013074A5DA261A24E5A130F4A5E180F61181F 61011F4C5A5C4E5A4EC7FC4D5A4D5A013F4B5A4A4A5AEF3FE0EF7F80017F4A48C8FC01FF EC1FFCB812F0178004FCC9FC423E7DBD45>I<013FB812F8A39026007FF0C7127F6E4814 0F18034B14011800A31978147F4B1570A502FF147092C7FCA3190017F0495D4A1301A216 07161F91B6FC495DA29138FC003F160F1607160301075D5CA219E0180119C0010FEC0700 4A90C712031980A218071900011F5E5C181EA2183E183C013F167C4A15FC4D5A1707017F 151F01FF4AB45AB9FCA2603D3E7DBD3E>I<013FB812E0A3903A007FF000016E48EB003F 180F4B14071803A31801147F4B15C0A514FF92C71270A395C7FC17F0495D5C1601160316 07161F49B65AA39138FC003F160F160701075D4A1303A5010F4AC8FC5C93C9FCA4131F5C A5133F5CA3137FEBFFF0B612F8A33B3E7DBD3B>I<4BB46C1370031F01F013F0037F9038 FC01E0913A03FF807E03913A0FF8000F83DA1FE0EB07C7DA7F80EB01EF4AC812FFD903FE 16C04948157F4948153F495A4948151F495A4948168091C9120F5A485AA2485A000F1800 4982121FA248485EA295C7FC485AA412FF5BA6043FB512E05BA29339001FFC00715AA260 7F127FA2171F123F6D5EA2121F7F000F163F6C7E6C6C4B5A7F6C6C15FF6C6DEB01EFD93F C0EB07C7D91FF0EB1F87D907FE9038FE03800101B5EAF8016D6C01E0C8FCDA07FEC9FC3C 4276BF47>I<013FB5D8F807B6FC04F015FEA29026007FF0C7380FFE006E486E5AA24B5D A4180F147F4B5DA4181F14FF92C85BA4183F5B4A5EA491B8FC5B6102FCC8127FA318FF13 074A93C7FCA45F130F4A5DA41703131F4A5DA41707133F4A5DA3017F150F496C4A7EB6D8 E01FB512FC6115C0483E7DBD44>I<011FB512FC5BA29039003FF8006E5AA25DA5143F5D A5147F5DA514FF92C7FCA55B5CA513035CA513075CA5130F5CA5131F5CA3133F497E007F B512F0A2B6FC263E7EBD21>I<013FB500F8010FB5FC4C5BA29026007FF0C7000313E06E 486E130019FC4B15F04E5A4E5A4E5A061EC7FC027F5D4B5C4D5A4D5AEF07804DC8FC02FF 141E92C7127C5FEE01E04C5A4C5A49021FC9FC4A5B5E4C7E5D03077F01035B9139FC1F3F E0153C4B6C7E15F09139FFE00FF84913C092380007FC5C4A6D7E5C707E130F4A6D7F8417 7F717EA2011F6F7E5C717EA2717EA2013F6F7E5C84A2017F83496C4A13E0B600E0017F13 FFA24B90B6FC483E7DBD47>75 D<013FB512FEA25E9026007FF8C8FCEC3FE0A25DA5147F 5DA514FF92C9FCA55B5CA513035CA513075CA21838A21870130F5CA218E0A3011F15014A 15C01703A21707EF0F80013F151F4A143F177FEFFF00017F140301FF143FB9FC5FA2353E 7DBD39>I<90263FFFF093381FFFF85013F0629026007FF8EFF000023F4D5AA2023B9338 01DFC0A2DA39FCED039FA2F1073F14790271040E5BEC70FE191C19381A7F02F01670DAE0 7F94C7FC19E0A2F001C06201016D6C495A02C05FF00700A2180E6F6C14010103161C0280 03385BA218706F7EF0E00313070200DA01C05BA2923907F00380A294380700075B010E90 2603F80E5C5FA25F190F011E6D6C5A011C605FA2EEFDC0DB00FF141F013C5D013860013C 92C7FC017C5C01FE027E143F2607FF80017C4A7EB500FC037FB512E004785E4A1338553E 7CBD53>I<90263FFFE0023FB5FC6F16FEA29026003FF8020313C0021F030013004A6C15 7C023B163C6F15381439810238167802787FDA707F157082153F82031F15F002F07FDAE0 0F5D8215078203031401010180DAC0015D82811780047F1303010315C04A013F5C17E016 1F17F0040F1307010715F891C7000791C7FC17FC160317FE04015B4915FF010E6E130E18 8E177F18CEEF3FDE011E16FE011C6F5AA2170FA21707133C01386F5A133C017C150113FE 2607FF801400B512FC18705C483E7DBD44>I<923803FF80031F13F09238FE01FE913903 F0003FDA0FC0EB1FC0DA3F80EB07E0027EC76C7E49486E7E49488149486E7E4948157F49 5A013F17804948ED3FC049C9FCA24848EE1FE012035B000718F05B120FA2485A19F8123F 5BA2127FA219F04848163FA5F07FE0A35BF0FFC0A219805F19007F4D5A127F4D5A60003F 160F6D5E001F4C5A4D5A6C6C4B5A95C7FC6C6C15FE00034B5A6C6C4A5A6C6C4A5A017FEC 1FC06D6C495AD90FE001FEC8FC903903F807F80100B512C0DA0FFCC9FC3D4276BF47>I< 013FB612FEEFFFE018F8903B007FF0000FFC6E48EB01FF7113804BEC7FC0183F19E0F01F F0A2147F5D19F8A402FFED3FF092C8FCA219E0A2F07FC05B4AEDFF8019004D5A4D5AEF0F F80103ED3FE04A903801FF8091B648C7FC17F002FCCAFCA213075CA5130F5CA5131F5CA5 133F5CA3137F497EB612E0A25D3D3E7DBD3E>I<013FB612F017FF18E0903B007FF0003F F86E48EB07FCEF01FE4B6D7EF07F8019C0183F19E0147F4B15F0A502FFED7FE092C8FCA2 19C0F0FF80A2494B13004A5D4D5AEF0FF04D5AEF7F800103DA07FEC7FC91B612F0178091 39FC0007E0EE03F8EE00FC0107814A147F717EA284A2130F5CA484011F157F5CA4190201 3F17075CA2F0F00F017F170E496C143FB600E0011F131C94380FF83C4B01071378CA3801 FFE09438003F8040407DBD43>82 D<9238FF80070207EBE00F021FEBF81E91387F00FE02 FCEB1F3ED903F0EB0FFE49481307494813034AEB01FC49C7FC491400133E137E177C4915 78A57F1770A26D1500808080EB7FFEECFFE06D13FEEDFFC06D14F06D14FC010380010080 143F02031480DA003F13C015031500EE7FE0163F161FA2160F121CA31607160F003C16C0 A31780003E151F1700007E5D007F153E6D5C16FC01E0495AD87DF0495AD8FCFCEB0FC03A F87F803F8027F01FFFFEC7FCD8E00713F839C0007FC030427BBF33>I<0007B912F0A33C 0FFE000FF8003F01F0160F01C04A13034848160190C7FC121EF000E048141F5E1238A212 781270153F5E5AA3C81600157F5EA515FF93C9FCA55C5DA514035DA514075DA5140F5DA3 141FEC7FFC0003B7FCA33C3D76BC42>IIII<010FB500F090B512F85B5FD9003F9026 80003F1300DA0FFEC7EA1FF84BEC0FE00207168096C7FC6E6C141E181C6E6C143C606E6D 5B4D5ADB7FC05B4D5A92383FE0074DC8FC92381FF01E171C6F6C5A5F923807FCF0EEFDE0 6FB45A5F6F90C9FCA26F7FA2707EA216FF4B7FED03DF9238079FF0ED0F1F92380E0FF815 1C92383C07FC15784B6C7EEC01E04B6C7EEC038002076D7F4AC7FC021E6E7E5C02386E7E 5C02F06E7E495A49486E7E130749486E7E497E017F4B7E2603FFF091383FFF80007F01FC 49B512FEB55CA2453E7EBD44>II<010FB712FEA39239C00007FCD91FFCC7EA0FF814 F04AEC1FF00280EC3FE091C8EA7FC0013EEDFF80A2013C4A13004C5A494A5A4C5A13704C 5A4C5A494A5A4C5AA290C74890C7FC4B5A4B5A4B5AA24B5A4B5A4B5A4B5AA24A90C8FC4A 5A4A5A4A5AA24A5A4A5A4A48EB01C04A5AEF03804990C7FC495A495A494814071800495A 49485C495A495A171E4890C8123E485A4848157E484815FE4C5A484814074848141F4848 EB01FFB8FC5FA2373E7BBD38>I E %EndDVIPSBitmapFont %DVIPSBitmapFont: Fi cmbx10 10.95 50 /Fi 50 123 df12 D45 D48 D<140F143F5C495A130F48B5FCB6FCA313F7EAFE071200B3B3A8007FB612F0A5243C78BB 34>I<903803FF80013F13F890B512FE00036E7E4881260FF80F7F261FC0037F4848C67F 486C6D7E6D6D7E487E6D6D7EA26F1380A46C5A6C5A6C5A0007C7FCC8FC4B1300A25E153F 5E4B5AA24B5A5E4A5B4A5B4A48C7FC5D4A5AEC1FE04A5A4A5A9139FF000F80EB01FC495A 4948EB1F00495AEB1F8049C7FC017E5C5B48B7FC485D5A5A5A5A5AB7FC5EA4293C7BBB34 >I<903801FFE0010F13FE013F6D7E90B612E04801817F3A03FC007FF8D807F06D7E82D8 0FFC131F6D80121F7FA56C5A5E6C48133FD801F05CC8FC4B5A5E4B5A4A5B020F5B902607 FFFEC7FC15F815FEEDFFC0D9000113F06E6C7E6F7E6F7E6F7E1780A26F13C0A217E0EA0F C0487E487E487E487EA317C0A25D491580127F49491300D83FC0495A6C6C495A3A0FFE01 FFF86CB65A6C5DC61580013F49C7FC010313E02B3D7CBB34>II<00071538D80FE0EB01F801FE133F90B6FC5E5E5E 5E93C7FC5D15F85D15C04AC8FC0180C9FCA9ECFFC0018713FC019F13FF90B67E020113E0 9039F8007FF0496D7E01C06D7E5B6CC77FC8120F82A31780A21207EA1FC0487E487E12FF 7FA21700A25B4B5A6C5A01805C6CC7123F6D495AD81FE0495A260FFC075B6CB65A6C92C7 FCC614FC013F13F0010790C8FC293D7BBB34>II<121F7F13F890B712F0A45A17E017C0178017005E5E5A007EC7EA01F8 4B5A007C4A5A4B5A4B5A93C7FC485C157E5DC7485A4A5AA24A5A140F5D141F143F5D147F A214FF92C8FC5BA25BA3495AA3130FA5131FAA6D5A6D5A6D5A2C3F7ABD34>II<903801FFE0010F13FC013F13FF90B612C04801E07F489038003FF048 486D7E000F6E7E485A6F7E123F48488081178012FFA217C0A517E0A4007F5CA4003F5C6C 7E5D6C7E00075C3903FF80FB6C13FF6C6C13F36D13C3010F018313C090380008031400A2 4B1380EA03F0487E486C1500487E4B5AA25E151F4B5A495C6C48EBFFE049485B2607FC0F 5B6CB6C7FC6C14FC6C14F06D13C0D90FFEC8FC2B3D7CBB34>I<16FCA24B7EA24B7EA34B 7FA24B7FA34B7FA24B7FA34B7F157C03FC7FEDF87FA2020180EDF03F0203804B7E020781 15C082020F814B7E021F811500824A81023E7F027E81027C7FA202FC814A147F49B77EA3 4982A2D907E0C7001F7F4A80010F835C83011F8391C87E4983133E83017E83017C81B500 FC91B612FCA5463F7CBE4F>65 DI<922607FFC0130E92B500FC131E020702FF133E023FEDC07E91 B7EAE1FE01039138803FFB499039F80003FF4901C01300013F90C8127F4948151FD9FFF8 150F48491507485B4A1503481701485B18004890CAFC197E5A5B193E127FA349170012FF AC127F7F193EA2123FA27F6C187E197C6C7F19FC6C6D16F86C6D150119F06C6D15036C6D ED07E0D97FFEED0FC06D6CED3F80010F01C0ECFF006D01F8EB03FE6D9039FF801FFC0100 91B55A023F15E002071580020002FCC7FC030713C03F407ABE4C>II II<922607FFC0130E92B500FC131E020702FF133E023FEDC07E91B7EAE1 FE01039138803FFB499039F80003FF4901C01300013F90C8127F4948151FD9FFF8150F48 491507485B4A1503481701485B18004890CAFC197E5A5B193E127FA34994C7FC12FFAB04 07B612FC127F7FA3003F92C7383FFE00A27F7EA26C7FA26C7F6C7FA26C7F6C7FD97FFE15 7F6D6C7E010F01E014FF6D01F813036D9038FF801F010091B512F3023F15C00207ED803E 02009138FE000E030701E090C7FC46407ABE52>III 76 D78 DII82 D<903A03FFC001C0011FEBF803 017FEBFE0748B6128F4815DF48010013FFD80FF8130F48481303497F4848EB007F127F49 143F161F12FF160FA27F1607A27F7F01FC91C7FCEBFF806C13F8ECFFC06C14FCEDFF806C 15E016F86C816C816C816C16806C6C15C07F010715E0EB007F020714F0EC003F15030300 13F8167F163F127800F8151FA2160FA27EA217F07E161F6C16E06D143F01E015C001F8EC 7F8001FEEB01FF9026FFE00713004890B55A486C14F8D8F81F5CD8F00314C027E0003FFE C7FC2D407ABE3A>I<003FB912FCA5903BFE003FFE003FD87FF0EE0FFE01C01603491601 90C71500197E127EA2007C183EA400FC183F48181FA5C81600B3AF010FB712F8A5403D7C BC49>I<903807FFC0013F13F848B6FC48812607FE037F260FF8007F6DEB3FF0486C806F 7EA36F7EA26C5A6C5AEA01E0C8FC153F91B5FC130F137F3901FFFE0F4813E0000F138038 1FFE00485A5B485A12FF5BA4151F7F007F143F6D90387BFF806C6C01FB13FE391FFF07F3 6CEBFFE100031480C6EC003FD91FF890C7FC2F2B7DA933>97 D<13FFB5FCA512077EAFED FFE0020713FC021FEBFF80027F80DAFF8113F09139FC003FF802F06D7E4A6D7E4A13074A 80701380A218C082A318E0AA18C0A25E1880A218005E6E5C6E495A6E495A02FCEB7FF090 3AFCFF01FFE0496CB55AD9F01F91C7FCD9E00713FCC7000113C033407DBE3A>IIIII<903A03FF8007F0013F9038F83FF8499038FC FFFC48B712FE48018313F93A07FC007FC34848EB3FE1001FEDF1FC4990381FF0F8170000 3F81A7001F5DA26D133F000F5D6C6C495A3A03FF83FF8091B5C7FC4814FC01BF5BD80F03 138090CAFCA2487EA27F13F06CB6FC16F016FC6C15FF17806C16C06C16E01207001F16F0 393FE000034848EB003F49EC1FF800FF150F90C81207A56C6CEC0FF06D141F003F16E001 F0147FD81FFC903801FFC02707FF800F13006C90B55AC615F8013F14E0010101FCC7FC2F 3D7DA834>I<13FFB5FCA512077EAFED1FF8EDFFFE02036D7E4A80DA0FE07F91381F007F 023C805C4A6D7E5CA25CA35CB3A4B5D8FE0FB512E0A5333F7CBE3A>II<13FFB5FCA512077EB3B3AFB512FCA5163F7CBE1D>108 D<01FFD91FF8ECFFC0B590 B5010713F80203DAC01F13FE4A6E487FDA0FE09026F07F077F91261F003FEBF801000701 3EDAF9F0806C0178ECFBC04A6DB4486C7FA24A92C7FC4A5CA34A5CB3A4B5D8FE07B5D8F0 3FEBFF80A551297CA858>I<01FFEB1FF8B5EBFFFE02036D7E4A80DA0FE07F91381F007F 0007013C806C5B4A6D7E5CA25CA35CB3A4B5D8FE0FB512E0A533297CA83A>II<01FFEBFFE0B5000713FC021FEBFF80027F80 DAFF8113F09139FC007FF8000701F06D7E6C496D7E4A130F4A6D7E1880A27013C0A38218 E0AA4C13C0A318805E18005E6E5C6E495A6E495A02FCEBFFF0DAFF035B92B55A029F91C7 FC028713FC028113C00280C9FCACB512FEA5333B7DA83A>I<3901FE01FE00FF903807FF 804A13E04A13F0EC3F1F91387C3FF8000713F8000313F0EBFFE0A29138C01FF0ED0FE091 388007C092C7FCA391C8FCB3A2B6FCA525297DA82B>114 D<90383FFC1E48B512BE0007 14FE5A381FF00F383F800148C7FC007E147EA200FE143EA27E7F6D90C7FC13F8EBFFE06C 13FF15C06C14F06C806C806C806C80C61580131F1300020713C014000078147F00F8143F 151F7EA27E16806C143F6D140001E013FF9038F803FE90B55A15F0D8F87F13C026E00FFE C7FC222B7DA929>IIII120 DI<003FB612F8A4D9F80113F001C014E0495A494813C04A 1380007E15005C4A5A007C5C147F4A5A495B5DC65A495B495BA249EB007C495A5C137F49 4813FC484913F85C5A48EBC00114804814034813004848130749131F007FECFFF0B7FCA4 26287DA72E>I E %EndDVIPSBitmapFont %DVIPSBitmapFont: Fj cmr10 10.95 92 /Fj 92 124 df<4AB4EB0FE0021F9038E03FFC913A7F00F8FC1ED901FC90383FF03FD907 F090397FE07F80494801FF13FF4948485BD93F805C137F0200ED7F00EF003E01FE6D91C7 FC82ADB97EA3C648C76CC8FCB3AE486C4A7E007FD9FC3FEBFF80A339407FBF35>11 DIII<121EEA7F80EAFFC0A9EA7F80ACEA3F00AC 121EAB120CC7FCA8121EEA7F80A2EAFFC0A4EA7F80A2EA1E000A4179C019>33 D<001E130F397F803FC000FF137F01C013E0A201E013F0A3007F133F391E600F30000013 00A401E01370491360A3000114E04913C00003130101001380481303000EEB070048130E 0018130C0038131C003013181C1C7DBE2D>I<4B6C130C4B6C131EA20307143EA24C133C A2030F147CA293C71278A24B14F8A2031E5CA2033E1301A2033C5CA3037C1303A203785C A203F81307A24B5CA20201140F007FBAFCBB1280A26C1900C72707C0003EC8FC4B133CA3 020F147CA292C71278A24A14F8A2021E5CA3023E1301007FBAFCBB1280A26C1900C727F8 0007C0C8FC4A5CA20101140FA24A91C9FCA301035CA24A131EA20107143EA24A133CA201 0F147CA291C71278A34914F8A2011E5CA2013E1301A2013C5CA201186D5A41517BBE4C> I<14E0A4EB07FC90383FFF8090B512E03901F8E3F03903E0E0FCD807C0133CD80F807FD8 1F007F003E80003C1580007C140316C00078141F00F8143F157FA47EED3F806CEC0E0092 C7FC127F138013C0EA3FF013FEEA1FFF6C13FC6C13FF6C14C06C806C6C13F8011F7F1303 01007FECE7FF14E102E01380157F153FED1FC0A2003E140F127FD8FF801307A5130000FC 158000F0140F1270007815005D6C141E153E6C5C6C5C3907C0E1F03903F8EFE0C6B51280 D93FFEC7FCEB0FF8EB00E0A422497BC32D>I<013F1603D9FFC04B7E2601E0E0150F2607 C070151F48486C4BC7FC023E157E48486C15FE48D90FC0EB03FC003ED90EF0EB0FF8DA0F 3F13FD007E903A070FFFF1F0007C0200EB03E0160000FC6D6C495A170F604DC8FC5F173E 5F17FC5F4C5A1603007CD907005B4C5A007E150F003E495C020E49C9FC003F5D6C49133E 260F803C5B023813FC6C6C485B3A01E0E001F03800FFC090273F0003E0133F90C70007EC FFC09339C001E0E0923A0F8007C070031F49487E0400143C033E90381F001C037E497F03 7C133E4B150F0201027E7F4B137C4A5A020702FCEB03805D4A5A141F92C7FC143E147E14 7C5CA2495A0103037CEB07005C4948147E010F033E5B4A160E49C8123F496F5B013E9238 0F803C49173801FC6F6C5A49923801E0E0496FB45A0160043FC7FC41497BC34C>II<121EEA7F8012FF13C0A213E0A3127FEA1E601200A413E013C0A312 011380120313005A120E5A1218123812300B1C79BE19>I<1430147014E0EB01C0EB0380 1307EB0F00131E133E133C5B13F85B12015B1203A2485AA2120F5BA2121F90C7FCA25AA3 123E127EA6127C12FCB2127C127EA6123E123FA37EA27F120FA27F1207A26C7EA212017F 12007F13787F133E131E7FEB07801303EB01C0EB00E014701430145A77C323>I<12C07E 12707E7E121E7E6C7E7F12036C7E7F12007F1378137CA27FA2133F7FA21480130FA214C0 A3130714E0A6130314F0B214E01307A614C0130FA31480A2131F1400A25B133EA25BA213 7813F85B12015B485A12075B48C7FC121E121C5A5A5A5A145A7BC323>II<1506150FB3A9 007FB912E0BA12F0A26C18E0C8000FC9FCB3A915063C3C7BB447>I<121EEA7F8012FF13 C0A213E0A3127FEA1E601200A413E013C0A312011380120313005A120E5A121812381230 0B1C798919>II<121EEA7F80A2EAFFC0A4EA7F80A2EA1E000A0A 798919>IIIIII<150E151E153EA2157EA215FE1401A21403 EC077E1406140E141CA214381470A214E0EB01C0A2EB0380EB0700A2130E5BA25B5BA25B 5B1201485A90C7FC5A120E120C121C5AA25A5AB8FCA3C8EAFE00AC4A7E49B6FCA3283E7E BD2D>I<00061403D80780131F01F813FE90B5FC5D5D5D15C092C7FC14FCEB3FE090C9FC ACEB01FE90380FFF8090383E03E090387001F8496C7E49137E497F90C713800006141FC8 13C0A216E0150FA316F0A3120C127F7F12FFA416E090C7121F12FC007015C012780038EC 3F80123C6CEC7F00001F14FE6C6C485A6C6C485A3903F80FE0C6B55A013F90C7FCEB07F8 243F7CBC2D>II<1238123C123F90 B612FCA316F85A16F016E00078C712010070EC03C0ED078016005D48141E151C153C5DC8 127015F04A5A5D14034A5A92C7FC5C141EA25CA2147C147814F8A213015C1303A31307A3 130F5CA2131FA6133FAA6D5A0107C8FC26407BBD2D>III< 121EEA7F80A2EAFFC0A4EA7F80A2EA1E00C7FCB3121EEA7F80A2EAFFC0A4EA7F80A2EA1E 000A2779A619>I<121EEA7F80A2EAFFC0A4EA7F80A2EA1E00C7FCB3121E127FEAFF80A2 13C0A4127F121E1200A412011380A3120313005A1206120E120C121C5A1230A20A3979A6 19>I<007FB912E0BA12F0A26C18E0CDFCAE007FB912E0BA12F0A26C18E03C167BA147> 61 DIII<15074B7EA34B7EA34B7EA34B7EA34B7E15E7A2913801C7FC15C3A291380381 FEA34AC67EA3020E6D7EA34A6D7EA34A6D7EA34A6D7EA34A6D7EA349486D7E91B6FCA249 819138800001A249C87EA24982010E157FA2011E82011C153FA2013C820138151FA20178 82170F13FC00034C7ED80FFF4B7EB500F0010FB512F8A33D417DC044>IIIIIIIII<011FB512FCA3D9000713006E5A1401B3B3A6123FEA7F80EAFFC0A44A5A 1380D87F005B007C130700385C003C495A6C495A6C495A2603E07EC7FC3800FFF8EB3FC0 26407CBD2F>IIIIIIIIII<003FB91280A3903AF0007FE001018090393FC0003F48C7ED1FC0007E17 07127C00781703A300701701A548EF00E0A5C81600B3B14B7E4B7E0107B612FEA33B3D7D BC42>IIII<007FB5D8C003B512E0A3C649C7EBFC00D93FF8EC3FE0 6D48EC1F806D6C92C7FC171E6D6C141C6D6C143C5F6D6C14706D6D13F04C5ADA7FC05B02 3F13036F485ADA1FF090C8FC020F5BEDF81E913807FC1C163C6E6C5A913801FF7016F06E 5B6F5AA26F7E6F7EA28282153FED3BFEED71FF15F103E07F913801C07F0203804B6C7EEC 07004A6D7E020E6D7E5C023C6D7E02386D7E14784A6D7E4A6D7F130149486E7E4A6E7E13 0749C86C7E496F7E497ED9FFC04A7E00076DEC7FFFB500FC0103B512FEA33F3E7EBD44> II<003FB712F8A391C7EA1FF013F8 01E0EC3FE00180EC7FC090C8FC003EEDFF80A2003C4A1300007C4A5A12784B5A4B5AA200 704A5AA24B5A4B5AA2C8485A4A90C7FCA24A5A4A5AA24A5AA24A5A4A5AA24A5A4A5AA249 90C8FCA2495A4948141CA2495A495AA2495A495A173C495AA24890C8FC485A1778485A48 4815F8A24848140116034848140F4848143FED01FFB8FCA32E3E7BBD38>II<486C13C00003130101001380481303000EEB 070048130E0018130C0038131C003013180070133800601330A300E01370481360A400CF EB678039FFC07FE001E013F0A3007F133FA2003F131F01C013E0390F0007801C1C73BE2D >II96 DII<49B4FC010F13E090383F00F8017C131E4848131F4848137F0007ECFF80485A5B12 1FA24848EB7F00151C007F91C7FCA290C9FC5AAB6C7EA3003FEC01C07F001F140316806C 6C13076C6C14000003140E6C6C131E6C6C137890383F01F090380FFFC0D901FEC7FC222A 7DA828>IIII<167C903903F801FF903A1FFF078F8090397E0FDE 1F9038F803F83803F001A23B07E000FC0600000F6EC7FC49137E001F147FA8000F147E6D 13FE00075C6C6C485AA23901F803E03903FE0FC026071FFFC8FCEB03F80006CAFC120EA3 120FA27F7F6CB512E015FE6C6E7E6C15E06C810003813A0FC0001FFC48C7EA01FE003E14 0048157E825A82A46C5D007C153E007E157E6C5D6C6C495A6C6C495AD803F0EB0FC0D800 FE017FC7FC90383FFFFC010313C0293D7EA82D>III<1478EB01 FEA2EB03FFA4EB01FEA2EB00781400AC147FEB7FFFA313017F147FB3B3A5123E127F38FF 807E14FEA214FCEB81F8EA7F01387C03F0381E07C0380FFF803801FC00185185BD1C>I< EA01FC12FFA3120712031201B292B51280A392383FFC0016E0168093C7FC153C5D5D4A5A EC07C04A5A4AC8FC143E147F4A7E13FD9038FFDFC0EC9FE0140F496C7E01FC7F496C7E14 01816E7E81826F7E151F826F7EA282486C14FEB539F07FFFE0A32B3F7EBE30>II<2701F801FE14FF00FF9027 07FFC00313E0913B1E07E00F03F0913B7803F03C01F80007903BE001F87000FC2603F9C0 6D487F000101805C01FBD900FF147F91C75B13FF4992C7FCA2495CB3A6486C496CECFF80 B5D8F87FD9FC3F13FEA347287DA74C>I<3901F801FE00FF903807FFC091381E07E09138 7803F000079038E001F82603F9C07F0001138001FB6D7E91C7FC13FF5BA25BB3A6486C49 7EB5D8F87F13FCA32E287DA733>I<14FF010713E090381F81F890387E007E01F8131F48 48EB0F804848EB07C04848EB03E0000F15F04848EB01F8A2003F15FCA248C812FEA44815 FFA96C15FEA36C6CEB01FCA3001F15F86C6CEB03F0A26C6CEB07E06C6CEB0FC06C6CEB1F 80D8007EEB7E0090383F81FC90380FFFF0010090C7FC282A7EA82D>I<3901FC03FC00FF 90381FFF8091387C0FE09039FDE003F03A07FFC001FC6C496C7E6C90C7127F49EC3F805B EE1FC017E0A2EE0FF0A3EE07F8AAEE0FF0A4EE1FE0A2EE3FC06D1580EE7F007F6E13FE91 38C001F89039FDE007F09039FC780FC0DA3FFFC7FCEC07F891C9FCAD487EB512F8A32D3A 7EA733>I<02FF131C0107EBC03C90381F80F090397F00387C01FC131CD803F8130E4848 EB0FFC150748481303121F485A1501485AA448C7FCAA6C7EA36C7EA2001F14036C7E1507 6C6C130F6C7E6C6C133DD8007E137990383F81F190380FFFC1903801FE0190C7FCAD4B7E 92B512F8A32D3A7DA730>I<3901F807E000FFEB1FF8EC787CECE1FE3807F9C100031381 EA01FB1401EC00FC01FF1330491300A35BB3A5487EB512FEA31F287EA724>I<90383FC0 603901FFF8E03807C03F381F000F003E1307003C1303127C0078130112F81400A27E7E7E 6D1300EA7FF8EBFFC06C13F86C13FE6C7F6C1480000114C0D8003F13E0010313F0EB001F EC0FF800E01303A214017E1400A27E15F07E14016C14E06CEB03C0903880078039F3E01F 0038E0FFFC38C01FE01D2A7DA824>I<131CA6133CA4137CA213FCA2120112031207001F B512C0B6FCA2D801FCC7FCB3A215E0A912009038FE01C0A2EB7F03013F138090381F8700 EB07FEEB01F81B397EB723>IIII II<001F B61280A2EBE0000180140049485A001E495A121C4A5A003C495A141F00385C4A5A147F5D 4AC7FCC6485AA2495A495A130F5C495A90393FC00380A2EB7F80EBFF005A5B4848130712 07491400485A48485BA248485B4848137F00FF495A90B6FCA221277EA628>II E %EndDVIPSBitmapFont %DVIPSBitmapFont: Fk cmr12 14.4 16 /Fk 16 116 df<120FEA3FC0EA7FE0EAFFF0A6EA7FE0EA3FC0EA0F000C0C768B21>46 D48 D50 D<160F5EA25E5EA25E5DA25D5DA25D151E151C153C5D157015F04A5A5D14035D4A5A 5C140E5C143C14385C14F05C495A13035C130749C7FC130E131E5B133813785B5B120148 5A5B120748C8FC120E121E5A123812785AB912F0A4C8000190C7FCAF4B7F4B7F020FB612 E0A434507DCF3B>52 D<000316C001C0140301F8141F903AFFC003FF8091B612005E5E5E 16E016804BC7FC019F13F8018113800180C9FCB0EC0FF0ECFFFE01836D7E903987F01FE0 90399F0007F801BE6D7E01F86D7E496D7E49EC7F805BEE3FC04915E0C9121F17F0A317F8 160FA317FCA5120EEA3F80487E12FF7FA217F85B161F5B48C813F012700078ED3FE0A26C 16C0167F6CEDFF80001F16006C6C495A6C6C13036C6CEB07F8D801F8EB1FF06CB4EB7FE0 6DB51280011F49C7FC010713F8010013C02E517ACE3B>I68 D86 D98 DI101 D<1378EA01FE487E487FA66C90C7FC6C5AEA007890C8FCB0 EB7F80B5FCA41203C6FC137FB3B3A43801FFE0B61280A419507CCF21>105 D<01FFD907FEEC03FFB590261FFFC0010F13E0037F01F0013F13F8912701F80FFC9038FC 07FE913D03C003FE01E001FF000390260700019038038000C6010E6D6C48C76C7E6D48DA 7F8E6E7E4A159CA24ADA3FF86E7E02605D14E04A5DA34A5DB3AD2601FFE0DAFFF0EC7FF8 B6D8C07F9026FFE03FB512F0A45C347CB363>109 D<01FFEB07FCB590383FFF8092B512 E0913901F00FF8913903C007FC000349C66C7EC6010E13016D486D7E5C143002706E7E14 6014E05CA35CB3AD2601FFE0903801FFE0B600C0B612C0A43A347CB341>II<01FFEB1F80B5EB7FF0913801FFF8913803E1FC91380783FE0003EB0F 07C6131EEB7F1C1438143091387003FC91386000F0160014E05CA45CB3AA8048487EB612 F0A427347DB32E>114 DI E %EndDVIPSBitmapFont %DVIPSBitmapFont: Fl cmbx12 17.28 20 /Fl 20 117 df65 D<4DB5ED03C0057F02F014070407B600FE140F047FDBFFC0131F4BB800F0133F030F05FC 137F033F9127F8007FFE13FF92B6C73807FF814A02F0020113C3020702C09138007FE74A 91C9001FB5FC023F01FC16074A01F08291B54882490280824991CB7E4949844949844949 8449865D49498490B5FC484A84A2484A84A24891CD127FA25A4A1A3F5AA348491A1FA448 99C7FCA25CA3B5FCB07EA380A27EA2F50FC0A26C7FA37E6E1A1F6C1D80A26C801D3F6C6E 1A00A26C6E616D1BFE6D7F6F4E5A7F6D6D4E5A6D6D4E5A6D6D4E5A6D6E171F6D02E04D5A 6E6DEFFF806E01FC4C90C7FC020F01FFEE07FE6E02C0ED1FF8020102F8ED7FF06E02FF91 3803FFE0033F02F8013F1380030F91B648C8FC030117F86F6C16E004071680DC007F02F8 C9FC050191CAFC626677E375>67 D70 D73 D80 D83 D<001FBEFCA64849C79126E0000F148002E0180091C8171F498601F8 1A0349864986A2491B7FA2491B3F007F1DC090C9181FA4007E1C0FA600FE1DE0481C07A5 CA95C7FCB3B3B3A3021FBAFCA663617AE070>I<913803FFFE027FEBFFF00103B612FE01 0F6F7E4916E090273FFE001F7FD97FE001077FD9FFF801017F486D6D7F717E486D6E7F85 717FA2717FA36C496E7FA26C5B6D5AEB1FC090C9FCA74BB6FC157F0207B7FC147F49B612 07010F14C0013FEBFE004913F048B512C04891C7FC485B4813F85A5C485B5A5CA2B55AA4 5FA25F806C5E806C047D7F6EEB01F96C6DD903F1EBFF806C01FED90FE114FF6C9027FFC0 7FC01580000191B5487E6C6C4B7E011F02FC130F010302F001011400D9001F90CBFC4943 7CC14E>97 D<92380FFFF04AB67E020F15F0023F15FC91B77E01039039FE001FFF4901F8 010113804901E0010713C04901804913E0017F90C7FC49484A13F0A2485B485B5A5C5A71 13E0485B7113C048701380943800FE0095C7FC485BA4B5FCAE7EA280A27EA2806C18FCA2 6C6D150119F87E6C6D15036EED07F06C18E06C6D150F6D6DEC1FC06D01E0EC7F806D6DEC FF00010701FCEB03FE6D9039FFC03FFC010091B512F0023F5D020F1580020102FCC7FCDA 000F13C03E437BC148>99 D<92380FFFC04AB512FC020FECFF80023F15E091B712F80103 D9FE037F499039F0007FFF011F01C0011F7F49496D7F4990C76C7F49486E7F4849804884 4A804884485B727E5A5C48717EA35A5C721380A2B5FCA391B9FCA41A0002C0CBFCA67EA3 80A27EA27E6E160FF11F806C183F6C7FF17F006C7F6C6D16FE6C17016D6C4B5A6D6D4A5A 6D01E04A5A6D6DEC3FE0010301FC49B45A6D9026FFC01F90C7FC6D6C90B55A021F15F802 0715E0020092C8FC030713F041437CC14A>101 DII105 D<903807FF80B6FCA6C6FC7F7FB3B3B3B3ADB712E0A623647BE32C>108 D<902607FF80D91FFFEEFFF8B691B500F00207EBFF80040702FC023F14E0041F02FF91B6 12F84C6F488193267FE07F6D4801037F922781FE001F9027E00FF0007FC6DA83F86D9026 F01FC06D7F6DD987F06D4A487F6DD98FC0DBF87EC7804C6D027C80039FC76E488203BEEE FDF003BC6E4A8003FC04FF834B5FA24B5FA24B94C8FCA44B5EB3B2B7D8F007B7D8803FB6 12FCA67E417BC087>I<902607FF80EB1FFFB691B512F0040714FC041F14FF4C8193267F E07F7F922781FE001F7FC6DA83F86D7F6DD987F07F6DD98FC0814C7F039FC78015BE03BC 8003FC825DA25DA25DA45DB3B2B7D8F007B71280A651417BC05A>I<923807FFE092B6FC 020715E0021F15F8027F15FE494848C66C6C7E010701F0010F13E04901C001037F49496D 7F4990C87F49486F7E49486F7E48496F13804819C04A814819E048496F13F0A24819F8A3 48496F13FCA34819FEA4B518FFAD6C19FEA46C6D4B13FCA36C19F8A26C6D4B13F0A26C19 E06C6D4B13C0A26C6D4B13806C6D4B13006D6C4B5A6D6D495B6D6D495B010701F0010F13 E06D01FE017F5B010090B7C7FC023F15FC020715E0020092C8FC030713E048437CC151> I114 D<913A3FFF8007800107B5EAF81F011FEC FE7F017F91B5FC48B8FC48EBE0014890C7121FD80FFC1407D81FF0801600485A007F167F 49153FA212FF171FA27F7F7F6D92C7FC13FF14E014FF6C14F8EDFFC06C15FC16FF6C16C0 6C16F06C826C826C826C82013F1680010F16C01303D9007F15E0020315F0EC001F150004 1F13F81607007C150100FC81177F6C163FA2171F7EA26D16F0A27F173F6D16E06D157F6D 16C001FEEDFF806D0203130002C0EB0FFE02FCEB7FFC01DFB65A010F5DD8FE0315C026F8 007F49C7FC48010F13E035437BC140>II E %EndDVIPSBitmapFont %DVIPSBitmapFont: Fm cmbx12 24.88 41 /Fm 41 123 df[<96380FFFFE060FB612E04DB712FC051F16FF94B912C0040784041F18 F8047F9126FC001F7F4BB6008001017F030702F8C8EA3FFF4B02E0030F7F033F02804B7F 4B49C9127F92B54893B57E4A02F05D4A4A4B804A4A5D4A4A84634A91C9FC4A5BA24A5B51 80755C91B5FC5EA3755CA2755C755C755CE23FFEC8FCF40FF899CAFCAF083FB612FCBFFC A9C702FCC912038787B3B3B3B2003FB800F0013FB812F0A9>116 144 123 271 129 12 D[33 70 111 270 65 39 D[158 145 120 272 175 65 D[143 142 120 269 165 I[<0803B500C0EE01F00703B600FEEE03F8077FDBFFE015070607B800FC150F 063F05FF151F4DBA00E0143F050F07F8147F053F07FE14FF94BC5B04039326F8000FECC0 03040F4BC86CEBF007043F03C0030F6D5A93B648C900036D5A4B03F09339007FFF3F0307 03C0051F90B5FC4B92CB7E033F02FC18034B02F08492B648844A0380193F4A92CD7E4A4A 864A4A864A02F0864A4A864A8991B65A494B874992CF7E4C885B494A885E498B494A88A2 495C8D90B65A8D5A5E48217FA24892D1FC223FA25A5DA248211FA3485CFA0FF09FC7FCA2 5AA45DA3B6FCB27EA381A47EA46C80FA07F0FA0FF87EA2817EA36C6F1D1F23F07E827E22 3F6D6E1EE0A26D6E1D7F23C06D6E1DFF7F705213806D806D55130070646D6F646D6F515A 6E6E1B1F6E6E515A6E6E515A6E6E1BFF6E6E505B6E6E505B6E6F4F5B6E03E04F90C7FC6F 6EF13FFE6F02FC4F5A030F02FF4E485A6F03C005075B030103F0051F5B6F03FE057F1380 043FDAFFE00303B5C8FC040F03FE033F13FC0403DBFFF80107B55A040093B812E0053F1A 80050F4FC9FC050119F8DD003F18C0060795CAFCDE007F16F0070393CBFCDF000314C0> 141 146 115 271 168 I[156 142 120 269 178 I[138 141 120 268 153 I[127 141 120 268 146 I[<0803B500C0EE01F00703B600FE4C7E077FDBFFE015070607B800FC150F06 3F05FF151F4DBA00E0143F050F07F8147F053F07FE14FF94BC5B04039326F8000FECC003 040F4BC86CEBF007043F03C0030F6D5A93B648C900036D5A4B03F09339007FFF3F030703 C0051F90B5FC4B92CB7E033F02FC18034B02F08492B648844A0380193F4A92CD7E4A4A86 4A4A864A02F0864A4A864A8991B65A494B874992CF7E4C885B494A885E498B494A88A249 5C8D90B65A8D5A5E48217FA24892D1FC223FA25A5DA248211FA3485C7C5A9FC9FCA25AA4 5DA3B6FCB27EA381A20A0FBB12F8A27EA46C80A36C98C96C02F8C7FCA2817EA36C81A27E 827E827FA26D80A26D806D80A26D806D80A26D816D816E806E806E806E6E97B6FC6E806E 806E03C0606E816F02F8606F02FE60030F6E606F03E0173F030103F85F6F03FF933801FF FC043F03E00307497E040F03FF033F497E040304FC0107B5EAE00F040093B8487E053FF2 0001050F07FCEB007F050107F0141FDD003F06C01407060795C81201DE007F04F8ED0070 0703048093C8FCDF000302E0CDFC>157 146 115 271 183 I[165 142 120 269 182 I[74 142 122 269 87 I[121 142 120 269 140 76 D[165 142 120 269 182 78 D[<97B512F0077FECFFE00607B712FE067FEEFFE0 0503B912FC051FF0FF80057F19E00403BB12FC040F9226E0007F14FF043F02FCC7000315 C04C02E0DA007F804BB60080031F14F8030702FCC9000314FE4B4A70804B02E0706C8003 7F0280051F14E092B6CB6C804A4A72804A4A72804A02F00600804A4A737F4A4A73804A8B 4A4A738091B6CD6C80494A7480A2494A7480494A7480498C4C86498D4C87498D494A7580 A290B68B4C87488EA24892CF6C80A3488E4B88A2488EA3484A761580A34823C0A5484A76 15E0A7B621F0B36C23E0A26F64A56C23C0A46F646C2380A36C23006F64A26C6AA270636C 6AA26C6A70636C6A70636D69A26D6E98B65AA26D6E505DA26D6E5092C7FC6D6870626D6E 505C6D686D6F4F5C6E6E4F5C6E6E4F5CA26E6E96B65A6E6E4E92C8FC6E6E4E5C020102FF 060F14F86E6F4D5C6F6E4D5C6F02F094B65A030F6E4C92C9FC6F02FE04075C03016E6C03 1F14F86F03F092B65A043F02FE020715C0040FDAFFF090B7CAFC040392B812FC04001AF0 051F198005074ECBFCDD007F17E0060F94CCFCDE007F15E0070002F0CDFC>148 146 115 271 175 I[137 142 120 269 159 I[163 144 120 269 173 82 D[<93260FFFF8163E4BB600E0153F031F03 FE5D037FDBFFC05C0203B800F05B020F05FC5B4A05FF5B027FF0C00F91B526FE000FECF0 1F010302C0D9007F6D5A4991C800076D5A4901FC030090B6FC4901F0163F4949160F4901 808290B5170192CBFC4849844849181F87484984A2484984874886A248498588A24887A3 88A2B58680A36E85A280A26E8580A2818103F0725A6C6E96C7FC15FE8116E06C15FEEEFF E017FF6C17F0F0FF806C18F8F1FFC06C19FCF2FF806C1AE01BF86C1AFE6C747E6D1AE088 6D866D866D1AFF6D876D87010087806E86020F86020386020086153F030F851501DB001F 19801601DC000F18C0EF007F060717E0F0003F070316F0F1003F1A0F080315F81A00871B 1F877514FCA287007F86486C85A288A388A36D86A31EF87FA37F1EF0A26D626D1CE0A27F 6D5013C0A26E1B806E96B5FC6E1B0002F8606E4E5B6E626E6C5F03E04D5B03F84D5B03FE 057F5BDBFFC093B55A04F803035C496CD9FF80021F91C7FCD9FC1F02FF49B55AD9F80792 B75A496C19F049C66149011F18804901074DC8FC90C817F848031F16C048030003FCC9FC 007C04011480>102 146 115 271 129 I[<000FC312F8A6488EA304C0C7001F4AC71201 03F8C8F0000F03C01C0192C9737E02FC1E1F4A1E0702E08A4A8A4A8A4890CA757EA24920 3F49201FA349200FA2492007A4492003007F8EA4498CA848487A1380A6CC99C7FCB3B3B3 B3AA030FBD12FCA9>145 140 120 267 162 I[162 144 120 269 179 I<93B512FC037FECFFF00207B8FC023F17E091B912F84918FE010772 7E499126C0007F14E04901E0C7000F80496D020380496D020014FE6F6F7F90B570806F6F 8085486E6F807380A27380A28885886C5CA26D4982886D5B6D5B010713C0010190CAFC90 CCFCA90603B7FC050FB8FC0403B9FC167F0307BAFC153F4AB7EA807F020FEDE000023F02 FCC7FC91B612E0010392C8FC4914FC011F14F04914C0495C90B548C9FC485C485C485C48 5C5A5D485CA24891CAFCA3B6FC5CA397B6FCA461806C60F107EF6C6E150F6F16CF6C183F 6FDB7F8F806C6EDBFF0F14E06C02FCDA03FE15FE6C6E91260FFC0791B5FC6C6E6CD93FF8 17806C923AF803FFF003013F91B6487E010FEF8000010394C77E010004FC141F021F03F0 140702010380DA007F1400DA000701F8CDFC695F79DD71>97 D[113 144 121 270 129 I<94387FFFF0041FB612E093B712FE0307707E031F17F092B97E4A18FE020784021F 9126F8000F14804A0280010014C04A49C74814E049B500F85C494A17F0494A5C495C494A 4A14F84991C8FC5D495B90B5FC5D5A485C7314F05A4B6F14E05A7314C0487214804B9338 3FFE00F20FF84896C8FCA4485CA5B6FCB07EA281A37EA36C80A37E6F18FE6CF201FFA26C 6E5F1CFE6C801B076C6EEF0FFC6D7F70EE1FF86DF13FF06D6E167F6D6EEEFFE06D02F84B 13C06D6E5D6D02FF030F13806D03C0023F1300023F02F0903801FFFC6E9126FF801F5B02 0792B65A6E18C0020060033F4CC7FC030716F8030016C0041F4AC8FCDC007F13C0585F78 DD67>I[113 144 120 270 129 I<94387FFFC0040FB6FC93B712E0030716FC031F16FF037F17C04AB912F0 0207DAF80380021F912680003F13FE4A49C7000F7F4A01F802038049B5486E804902C06E 6C7F494A6F7F4991C9FC49727F4949707F4B84498490B548707F5A4B198048855D481CC0 86481CE05D5A871DF05AA25D5AA21DF887A2B6FCA392BBFCA51DF00380CDFCA77EA4817E A37EA2817EA26CF307F06FF00FF87E816C1B1F6F19F06C1B3F6D6DF07FE06D7FF4FFC06D 6E4C13806D6E5E6D02F04C13006D6EEE1FFE6D6E4C5A6D6C01FFEEFFF86E02E002035B6E 02FC021F5B02079126FFC003B55A6E92B7C7FC020060033F17F8030F17E003011780DB00 3F03FCC8FC040315C0DC000F01F8C9FC5D5F7ADD6A>I[<95383FFF80050FB512F094B612 FE040781041F16C0047F824BB87E0307DAF8077F031FDAC00F7F4B49C6487F4B495B92B5 00F0814A4A5B4A5C4A93B612805F4A91C7FC5C5E5C5E5C731400A24C6E5B91B56F5BA273 5B070313E00700138097C8FCB3A4BA12F8A9C702FCCBFCB3B3B3B3A2003FB9FCA9>81 144 121 271 71 II[ 114 143 119 270 129 I[49 144 119 271 65 I[ 50 143 119 270 65 108 DII<94381FFFF00407B612C004 7F15FC0303B87E030F17E0037F17FC4ABAFC4A9126FC007F80020F02C0010714E04A49C8 80027F01F8033F13FC91B5486F7F4902C003077F494A6F804991C96C8049497080494971 7F49874949717FA290B548717F48884B83481D80A2481DC04B83481DE0A2481DF0A3484A 7114F8A4481DFCA5B61BFEAF6C1DFCA56C6E4D14F8A36C1DF0A36C1DE06F5F6C1DC0A26C 6E4D1480A26C1D006F5F6C646D6D4D5B6F94B5FC6D636D6D4C5C6D6E4B5C6D6E4B5C6D02 F0031F5C6D6E4B91C7FC6D6C01FE92B512FC6ED9FFC001075C6E02FC017F5C020791B812 C0020196C8FC6E6C17FC031F17F003031780DB007F03FCC9FC040715C0DC001F01F0CAFC 675F7ADD74>II114 D<92261FFFF814F80203B638C001FC023FEDFC0791B8121F010317FF 130F013F9038F8001F4990C8FCD9FFF8153F4801E0150F484915034849814890CAFC197F 4848173F191F485AA2007F180FA31907487EA27FA28002E0705A6E93C8FC14FC14FF15F0 6CECFF8016FCEEFFF06CEEFF8018F06C17FE727E6C18E0856C18FC6C846C727E6C856D84 011F846D841303010084023F83140F020183EC001FDB007F16801603DC000F15C0170018 3F060F14E0007F1703486C82727E857F85857FA2857F1BC07FA27F1B806D5F7F1B006E5E 6E5F6E163F6E4C5A02FC4C5A6E03035B6E6C4A5B03F0023F5B03FF0107B55A01F991B7C7 FCD9F07F16FCD9E01F16F0D9800716C0D9000193C8FC48D9003F14F8007C020349C9FC4B 5F78DD5C>I[72 132 124 258 90 III<007FB86C49B712FEA9C792C9000F02C0C7FC6E6E 030101F0C8FC715F6E6E4B5B6E6E4B5B6E4E90C9FC6E6E5E71151F6E6E4B5A6E6E4B5A6E 4E5A6F6E495B72495B6F6E495B6F806F6E4990CAFC6F4C5A72495A6F6E495A6F6E495A6F 03815B705E7014C307E75B7091B5CBFC705D705D705D6282705D715C8386718071807180 837180864D814D815F4D81874D814D81DDFFF3804C13E14C01C1804C0180814E6C804C6E 804C487F4C48824C486D804C486D804B496D804B497F73804B49834B90C86C804B486F80 4B48814B486F804B48844C6F804A71804A496F804A49814A90CA814A487180023F728001 0FB500E07080B8031FB812E0A9735C7CDB7B>120 D<007FB800C04AB71280A9D800034A CA000791C7FC6D080013F0775A6D6E4E5AA26E6E6064836E4F90C8FC836E4F5A836E4F5A A26E6E4C5AA26E6E5F1C3F6E6E5F1C7F836E4F5A846F4D5B846F4D90C9FCA26F6E4A5AA2 6F6E5D1B0F846F4D5A846F4D5A846F4D5AA26F6E4A5AA2706E5C627002C091CAFC6219E0 704B5A19F0704B5AA2706E485AA2706E485AA27002FE5B1A7F19FF704B5AA2715DA27192 CBFCA2715CA2715CA3715CA2715CA2715CA2715CA2725BA27290CCFCA3725AA2725AA24E 5AA24E5AA261187FA24E5AA24D5B13FE2603FF804A90CDFC000F13E0486D4A5A487F486D 4A5AA260B56C141F4D5AA24D5A17FF604C5B4A4990CEFC6C5D4C5A6C49EB3FFC4A495A6C 4948485A9026FE80075B270FFFC03F5B6C90B6CFFC6C5D6C15F86C6C5C011F14C0010749 D0FC9038007FE071857CDB7B>I<0003BC12F81CFCA51CF80480C7123F03F0C84814F048 028018E04AC9B612C04A5D02F04B15804A19004E5C4A5D4A4B5C6391C9485C604993B65A 634D5D495D98C7FC4D5C4D5C000F5E62494B5C4D5C94B6FC624C5D4C92C8FC5EC95D4C5C 5E4C5C614C5C93B6FC4B5D614B92C9FC5D4B5C604B5C5D4B4AEC07FC6092B65A5C604A92 C8EA0FF84A5C5C5F4A5C4A5C4A181F5F91B65A495D491AF094C9123F495C5B494A167F5E 494A16FF496090B65A4C5D484B5D484F13E04892C95A4B5E484A93B5FC481803484A151F 4B0203B6FC4891BAFCBDFCA21CC0A47E565C7ADB67>I E %EndDVIPSBitmapFont end %%EndProlog %%BeginSetup %%Feature: *Resolution 600dpi TeXDict begin %%EndSetup %%Page: 1 1 1 0 bop 240 1799 a Fm(CFITSIO)76 b(User's)g(Reference)i(Guide)727 2258 y Fl(An)53 b(In)l(terface)f(to)i(FITS)g(F)-13 b(ormat)53 b(Files)1263 2518 y(for)h(C)f(Programmers)1667 3013 y Fk(V)-10 b(ersion)38 b(2.5)1727 3916 y Fj(HEASAR)m(C)1764 4029 y(Co)s(de)30 b(662)1363 4142 y(Go)s(ddard)f(Space)i(Fligh)m(t)f (Cen)m(ter)1522 4255 y(Green)m(b)s(elt,)g(MD)i(20771)1857 4367 y(USA)1561 5239 y Fk(Decem)m(b)s(er)37 b(2004)p eop %%Page: 2 2 2 1 bop 0 299 a Fj(ii)p eop %%Page: 3 3 3 2 bop 0 1267 a Fm(Con)-6 b(ten)g(ts)0 1858 y Fi(1)84 b(In)m(tro)s(duction)3136 b(1)136 2020 y Fj(1.1)125 b(A)30 b(Brief)g(Ov)m(erview)84 b(.)46 b(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h (.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.) g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)131 b(1)136 2182 y(1.2)94 b(Sources)30 b(of)h(FITS)f(Soft)m(w)m(are)h(and)f(Information) 37 b(.)46 b(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g (.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)131 b(1)136 2344 y(1.3)94 b(Ac)m(kno)m(wledgemen)m(ts)60 b(.)46 b(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f (.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.) h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)131 b(2)136 2506 y(1.4)94 b(Legal)31 b(Stu\013)92 b(.)46 b(.)g(.)f(.)h(.)g(.)f(.)h(.)g (.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.) g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)131 b(3)0 2766 y Fi(2)119 b(Creating)34 b(the)h(CFITSIO)e(Library)2256 b(5)136 2928 y Fj(2.1)94 b(Building)28 b(the)i(Library)57 b(.)45 b(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.) g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g (.)f(.)131 b(5)345 3090 y(2.1.1)106 b(Unix)30 b(Systems)44 b(.)h(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g (.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.) f(.)131 b(5)345 3252 y(2.1.2)106 b(VMS)33 b(.)46 b(.)g(.)f(.)h(.)g(.)f (.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.) h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)131 b(7)345 3413 y(2.1.3)106 b(Windo)m(ws)30 b(PCs)g(.)45 b(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f (.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.) 131 b(7)345 3575 y(2.1.4)106 b(Macin)m(tosh)31 b(PCs)55 b(.)46 b(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.) f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f (.)131 b(7)136 3737 y(2.2)94 b(T)-8 b(esting)31 b(the)f(Library)i(.)46 b(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g (.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.) f(.)131 b(8)136 3899 y(2.3)94 b(Linking)29 b(Programs)h(with)f(CFITSIO) 45 b(.)g(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.) g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)131 b(9)136 4061 y(2.4)94 b(Getting)31 b(Started)g(with)e(CFITSIO)60 b(.)46 b(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.) h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)131 b(9)136 4223 y(2.5)94 b(Example)30 b(Program)86 b(.)46 b(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g (.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.) f(.)85 b(10)0 4483 y Fi(3)119 b(A)35 b(FITS)f(Primer)2917 b(13)0 4742 y(4)119 b(Programming)35 b(Guidelines)2482 b(15)136 4904 y Fj(4.1)94 b(CFITSIO)29 b(De\014nitions)42 b(.)j(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g (.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.) f(.)85 b(15)136 5066 y(4.2)94 b(Curren)m(t)30 b(Header)h(Data)h(Unit)d (\(CHDU\))87 b(.)46 b(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f (.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(17)136 5228 y(4.3)94 b(F)-8 b(unction)31 b(Names)f(and)g(V)-8 b(ariable)30 b(Datat)m(yp)s(es)41 b(.)46 b(.)g(.)g(.)f(.)h(.)g(.)f(.)h (.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(18)136 5390 y(4.4)94 b(Supp)s(ort)29 b(for)h(Unsigned)f(In)m(tegers)i (and)f(Signed)f(Bytes)86 b(.)46 b(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h (.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(19)136 5552 y(4.5)94 b(Dealing)31 b(with)e(Character)h(Strings)60 b(.)46 b(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.) h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(21)136 5714 y(4.6)94 b(Implicit)28 b(Data)k(T)m(yp)s(e)e(Con)m(v)m (ersion)64 b(.)46 b(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g (.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(22)1912 5942 y(iii)p eop %%Page: 4 4 4 3 bop 0 299 a Fj(iv)3310 b Fh(CONTENTS)136 555 y Fj(4.7)94 b(Data)32 b(Scaling)87 b(.)46 b(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g (.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.) f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(22)136 720 y(4.8)94 b(Supp)s(ort)29 b(for)h(IEEE)g(Sp)s(ecial)e(V)-8 b(alues)67 b(.)45 b(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g (.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(23)136 885 y(4.9)94 b(Error)30 b(Status)g(V)-8 b(alues)31 b(and)e(the)i(Error)e(Message)j(Stac)m(k)44 b(.)i(.)f(.)h(.)g(.)g(.)f (.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(23)136 1049 y(4.10)49 b(V)-8 b(ariable-Length)31 b(Arra)m(ys)f(in)f (Binary)h(T)-8 b(ables)30 b(.)46 b(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g (.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(24)136 1214 y(4.11)49 b(Multiple)29 b(Access)i(to)g(the)g(Same)f (FITS)g(File)f(.)45 b(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h (.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(25)136 1379 y(4.12)49 b(When)31 b(the)f(Final)f(Size)h(of)h(the)f (FITS)g(HDU)h(is)e(Unkno)m(wn)34 b(.)45 b(.)h(.)g(.)g(.)f(.)h(.)g(.)f (.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(26)136 1543 y(4.13)49 b(CFITSIO)29 b(Size)h(Limitations)39 b(.)46 b(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g (.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(26)0 1817 y Fi(5)f(Basic)36 b(CFITSIO)d(In)m(terface)h(Routines)2074 b(29)136 1982 y Fj(5.1)94 b(CFITSIO)29 b(Error)h(Status)g(Routines)88 b(.)45 b(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.) g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(29)136 2146 y(5.2)94 b(FITS)30 b(File)g(Access)h(Routines)f(.)46 b(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g (.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(30)136 2311 y(5.3)94 b(HDU)32 b(Access)f(Routines)71 b(.)46 b(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.) f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f (.)85 b(33)136 2476 y(5.4)94 b(Header)31 b(Keyw)m(ord)f(Read/W)-8 b(rite)32 b(Routines)39 b(.)45 b(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.) g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(35)345 2640 y(5.4.1)106 b(Keyw)m(ord)30 b(Reading)g(Routines)64 b(.)46 b(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.) f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(35)345 2805 y(5.4.2)106 b(Keyw)m(ord)30 b(W)-8 b(riting)30 b(Routines)85 b(.)46 b(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.) f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(37)136 2970 y(5.5)94 b(Primary)29 b(Arra)m(y)i(or)f(IMA)m(GE)i(Extension)d (I/O)h(Routines)53 b(.)45 b(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f (.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(39)136 3135 y(5.6)94 b(Image)32 b(Compression)e(.)46 b(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h (.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.) g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(42)136 3299 y(5.7)94 b(ASCI)s(I)29 b(and)h(Binary)g(T)-8 b(able)30 b(Routines)84 b(.)46 b(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g (.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(45)345 3464 y(5.7.1)106 b(Create)32 b(New)e(T)-8 b(able)83 b(.)46 b(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.) g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(45)345 3629 y(5.7.2)106 b(Column)29 b(Information)g(Routines)h(.)46 b(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g (.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(46)345 3793 y(5.7.3)106 b(Routines)30 b(to)h(Edit)e(Ro)m(ws)i(or)f(Columns)38 b(.)46 b(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.) f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(48)345 3958 y(5.7.4)106 b(Read)31 b(and)f(W)-8 b(rite)30 b(Column)f(Data)j(Routines)65 b(.)46 b(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.) f(.)h(.)g(.)f(.)85 b(50)345 4123 y(5.7.5)106 b(Ro)m(w)31 b(Selection)f(and)g(Calculator)f(Routines)87 b(.)46 b(.)g(.)f(.)h(.)g (.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(51)136 4287 y(5.8)94 b(Utilit)m(y)30 b(Routines)c(.)45 b(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f (.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.) h(.)g(.)f(.)85 b(53)345 4452 y(5.8.1)106 b(File)30 b(Chec)m(ksum)g (Routines)46 b(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g (.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(53)345 4617 y(5.8.2)106 b(Date)32 b(and)e(Time)f(Utilit)m(y)h (Routines)89 b(.)46 b(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g (.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(54)345 4781 y(5.8.3)106 b(General)31 b(Utilit)m(y)e(Routines)j(.)46 b(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g (.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(56)0 5055 y Fi(6)119 b(The)35 b(CFITSIO)e(Iterator)g(F)-9 b(unction)2154 b(63)136 5220 y Fj(6.1)94 b(The)30 b(Iterator)i(W)-8 b(ork)31 b(F)-8 b(unction)44 b(.)h(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g (.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.) f(.)h(.)g(.)f(.)85 b(64)136 5385 y(6.2)94 b(The)30 b(Iterator)i(Driv)m (er)e(F)-8 b(unction)77 b(.)46 b(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.) h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h (.)g(.)f(.)85 b(66)136 5549 y(6.3)94 b(Guidelines)28 b(for)i(Using)g(the)g(Iterator)i(F)-8 b(unction)44 b(.)i(.)g(.)f(.)h(.) g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g (.)f(.)85 b(67)136 5714 y(6.4)94 b(Complete)31 b(List)e(of)i(Iterator)g (Routines)61 b(.)46 b(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g (.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(68)p eop %%Page: 5 5 5 4 bop 0 299 a Fh(CONTENTS)3334 b Fj(v)0 555 y Fi(7)119 b(Celestial)34 b(Co)s(ordinate)h(System)f(Routines)1882 b(71)136 717 y Fj(7.1)125 b(Self-con)m(tained)30 b(W)m(CS)g(Routines)e (.)46 b(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f (.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(72)0 978 y Fi(8)119 b(Hierarc)m(hical)36 b(Grouping)g(Routines)2163 b(75)136 1140 y Fj(8.1)94 b(Grouping)29 b(T)-8 b(able)30 b(Routines)86 b(.)46 b(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h (.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.) g(.)f(.)85 b(76)136 1302 y(8.2)94 b(Group)30 b(Mem)m(b)s(er)g(Routines) g(.)46 b(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.) h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(78)0 1563 y Fi(9)119 b(Sp)s(ecialized)36 b(CFITSIO)d(In)m(terface)h (Routines)1777 b(81)136 1725 y Fj(9.1)94 b(FITS)30 b(File)g(Access)h (Routines)f(.)46 b(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g (.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.) f(.)85 b(81)136 1887 y(9.2)94 b(HDU)32 b(Access)f(Routines)71 b(.)46 b(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.) f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f (.)85 b(84)136 2049 y(9.3)94 b(Sp)s(ecialized)29 b(Header)h(Keyw)m(ord) h(Routines)73 b(.)45 b(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h (.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(86)345 2211 y(9.3.1)106 b(Header)31 b(Information)e(Routines)63 b(.)46 b(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.) h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(86)345 2373 y(9.3.2)106 b(Read)31 b(and)f(W)-8 b(rite)30 b(the)h(Required)e(Keyw)m (ords)51 b(.)46 b(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f (.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(86)345 2536 y(9.3.3)106 b(W)-8 b(rite)31 b(Keyw)m(ord)f(Routines)25 b(.)46 b(.)f(.)h(.)g(.)f(.) h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f (.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(88)345 2698 y(9.3.4)106 b(Insert)30 b(Keyw)m(ord)g(Routines)88 b(.)45 b(.)h(.)g(.)f(.)h(.)g(.)g (.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.) f(.)h(.)g(.)f(.)85 b(90)345 2860 y(9.3.5)106 b(Read)31 b(Keyw)m(ord)f(Routines)44 b(.)i(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.) g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g (.)f(.)85 b(91)345 3022 y(9.3.6)106 b(Mo)s(dify)29 b(Keyw)m(ord)i (Routines)k(.)45 b(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g (.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(92)345 3184 y(9.3.7)106 b(Up)s(date)31 b(Keyw)m(ord)f(Routines)25 b(.)45 b(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.) g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(93)136 3346 y(9.4)94 b(De\014ne)31 b(Data)h(Scaling)d(and)h(Unde\014ned)f (Pixel)g(P)m(arameters)43 b(.)j(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f (.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(94)136 3508 y(9.5)94 b(Sp)s(ecialized)29 b(FITS)g(Primary)g(Arra)m(y)i(or)f(IMA)m(GE)h (Extension)f(I/O)g(Routines)54 b(.)46 b(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.) 85 b(95)136 3670 y(9.6)94 b(Sp)s(ecialized)29 b(FITS)g(ASCI)s(I)g(and)h (Binary)f(T)-8 b(able)30 b(Routines)86 b(.)46 b(.)g(.)g(.)f(.)h(.)g(.)f (.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(99)345 3832 y(9.6.1)106 b(General)31 b(Column)d(Routines)50 b(.)45 b(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.) g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)85 b(99)345 3994 y(9.6.2)106 b(Lo)m(w-Lev)m(el)32 b(T)-8 b(able)30 b(Access)h(Routines)39 b(.)46 b(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f (.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(100)345 4156 y(9.6.3)106 b(W)-8 b(rite)31 b(Column)e(Data)j(Routines) 51 b(.)46 b(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f (.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(100)345 4318 y(9.6.4)106 b(Read)31 b(Column)d(Data)k(Routines)71 b(.)46 b(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.) h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(102)0 4579 y Fi(10)67 b(Extended)35 b(File)f(Name)g(Syn)m(tax)2278 b(105)136 4741 y Fj(10.1)49 b(Ov)m(erview)83 b(.)46 b(.)g(.)g(.)f(.)h (.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.) g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g (.)f(.)40 b(105)136 4903 y(10.2)49 b(Filet)m(yp)s(e)60 b(.)45 b(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.) g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g (.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(108)345 5066 y(10.2.1)61 b(Notes)32 b(ab)s(out)e(HTTP)g(pro)m(xy)g(serv)m(ers)k(.)46 b(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f (.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(108)345 5228 y(10.2.2)61 b(Notes)32 b(ab)s(out)e(the)h(ro)s(ot)f(\014let)m(yp)s(e)67 b(.)46 b(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.) h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(108)345 5390 y(10.2.3)61 b(Notes)32 b(ab)s(out)e(the)h(shmem)e(\014let)m(yp)s (e:)69 b(.)46 b(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h (.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(110)136 5552 y(10.3)49 b(Base)32 b(Filename)88 b(.)45 b(.)h(.)g(.)f(.)h(.)g(.)g(.)f (.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.) h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(111)136 5714 y(10.4)49 b(Output)30 b(File)f(Name)i(when)f(Op)s(ening) e(an)i(Existing)f(File)79 b(.)45 b(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g (.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(113)p eop %%Page: 6 6 6 5 bop 0 299 a Fj(vi)3310 b Fh(CONTENTS)136 555 y Fj(10.5)49 b(T)-8 b(emplate)31 b(File)f(Name)h(when)e(Creating)h(a)h(New)f(File)55 b(.)46 b(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.) f(.)h(.)g(.)f(.)40 b(114)136 721 y(10.6)49 b(Image)32 b(Tile-Compression)27 b(Sp)s(eci\014cation)89 b(.)45 b(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g (.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(114)136 887 y(10.7)49 b(HDU)32 b(Lo)s(cation)e(Sp)s(eci\014cation)45 b(.)g(.)h(.)g(.)f(.)h(.) g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g (.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(115)136 1053 y(10.8)49 b(Image)32 b(Section)38 b(.)46 b(.)f(.)h(.)g(.)f(.)h(.)g(.)g (.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.) f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(116)136 1219 y(10.9)49 b(Column)29 b(and)h(Keyw)m(ord)g(Filtering)e (Sp)s(eci\014cation)89 b(.)45 b(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f (.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(117)136 1385 y(10.10)t(Ro)m(w)31 b(Filtering)e(Sp)s(eci\014cation)80 b(.)45 b(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.) g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(118)345 1551 y(10.10.1)16 b(General)31 b(Syn)m(tax)44 b(.)i(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f (.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.) 40 b(119)345 1718 y(10.10.2)16 b(Bit)31 b(Masks)43 b(.)j(.)g(.)f(.)h(.) g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g (.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(121)345 1884 y(10.10.3)16 b(V)-8 b(ector)32 b(Columns)91 b(.)46 b(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.) h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(122)345 2050 y(10.10.4)16 b(Go)s(o)s(d)30 b(Time)g(In)m(terv)-5 b(al)30 b(Filtering)59 b(.)46 b(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g (.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(123)345 2216 y(10.10.5)16 b(Spatial)29 b(Region)i(Filtering)56 b(.)46 b(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.) h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(124)345 2382 y(10.10.6)16 b(Example)30 b(Ro)m(w)h(Filters)f(.)45 b(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f (.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(126)136 2548 y(10.11)35 b(Binning)28 b(or)i(Histogramming)g(Sp)s (eci\014cation)f(.)46 b(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g (.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(127)0 2828 y Fi(11)32 b(T)-9 b(emplate)34 b(Files)2933 b(131)136 2994 y Fj(11.1)49 b(Detailed)31 b(T)-8 b(emplate)30 b(Line)g(F)-8 b(ormat)48 b(.)e(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.) g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(131)136 3160 y(11.2)49 b(Auto-indexing)29 b(of)i(Keyw)m(ords)73 b(.)45 b(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.) g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(132)136 3326 y(11.3)49 b(T)-8 b(emplate)31 b(P)m(arser)g(Directiv)m (es)85 b(.)45 b(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h (.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(133)136 3492 y(11.4)49 b(F)-8 b(ormal)31 b(T)-8 b(emplate)31 b(Syn)m(tax)j(.)46 b(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.) h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h (.)g(.)f(.)40 b(133)136 3658 y(11.5)49 b(Errors)63 b(.)46 b(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g (.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.) g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(134)136 3824 y(11.6)49 b(Examples)71 b(.)46 b(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g (.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.) f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(134)0 4105 y Fi(12)67 b(Lo)s(cal)35 b(FITS)g(Con)m(v)m(en)m(tions)2462 b(137)136 4271 y Fj(12.1)49 b(64-Bit)32 b(Long)f(In)m(tegers)61 b(.)45 b(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.) g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g (.)f(.)40 b(137)136 4437 y(12.2)49 b(Long)31 b(String)e(Keyw)m(ord)h(V) -8 b(alues.)64 b(.)46 b(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f (.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.) 40 b(138)136 4603 y(12.3)49 b(Arra)m(ys)31 b(of)f(Fixed-Length)h (Strings)d(in)h(Binary)h(T)-8 b(ables)77 b(.)46 b(.)f(.)h(.)g(.)g(.)f (.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(139)136 4769 y(12.4)49 b(Keyw)m(ord)31 b(Units)e(Strings)40 b(.)46 b(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.) f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f (.)40 b(139)136 4935 y(12.5)49 b(HIERAR)m(CH)31 b(Con)m(v)m(en)m(tion)g (for)f(Extended)g(Keyw)m(ord)g(Names)91 b(.)46 b(.)f(.)h(.)g(.)f(.)h(.) g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(140)136 5101 y(12.6)49 b(Tile-Compressed)29 b(Image)i(F)-8 b(ormat)52 b(.)46 b(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.) h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(140)0 5382 y Fi(13)67 b(Optimizing)34 b(Programs)2588 b(143)136 5548 y Fj(13.1)49 b(Ho)m(w)32 b(CFITSIO)c(Manages)k(Data)g (I/O)78 b(.)46 b(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.) h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(143)136 5714 y(13.2)49 b(Optimization)29 b(Strategies)76 b(.)46 b(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.) h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)g(.)f(.)h(.)g(.)f(.)h(.)g(.)f(.)40 b(144)p eop %%Page: 7 7 7 6 bop 0 299 a Fh(CONTENTS)3284 b Fj(vii)0 555 y Fi(A)57 b(Index)35 b(of)g(Routines)2789 b(147)0 806 y(B)62 b(P)m(arameter)34 b(De\014nitions)2598 b(151)0 1057 y(C)60 b(CFITSIO)33 b(Error)i(Status)f(Co)s(des)2255 b(157)p eop %%Page: 8 8 8 7 bop 0 299 a Fj(viii)3258 b Fh(CONTENTS)p eop %%Page: 1 9 1 8 bop 0 1225 a Fg(Chapter)65 b(1)0 1687 y Fm(In)-6 b(tro)6 b(duction)0 2216 y Ff(1.1)180 b(A)45 b(Brief)g(Ov)l(erview)0 2495 y Fj(CFITSIO)38 b(is)h(a)h(mac)m(hine-indep)s(enden)m(t)e(library) f(of)j(routines)e(for)i(reading)f(and)g(writing)e(data)k(\014les)d(in)h (the)0 2608 y(FITS)c(\(Flexible)f(Image)i(T)-8 b(ransp)s(ort)34 b(System\))h(data)h(format.)56 b(It)35 b(can)h(also)f(read)g(IRAF)h (format)f(image)h(\014les)0 2721 y(and)g(ra)m(w)h(binary)e(data)i(arra) m(ys)g(b)m(y)g(con)m(v)m(erting)h(them)e(on)h(the)g(\015y)f(in)m(to)h (a)g(virtual)e(FITS)h(format)h(\014le.)59 b(This)0 2833 y(library)30 b(is)i(written)g(in)f(ANSI)i(C)f(and)g(pro)m(vides)g(a)h (p)s(o)m(w)m(erful)e(y)m(et)j(simple)d(in)m(terface)i(for)g(accessing)g (FITS)f(\014les)0 2946 y(whic)m(h)j(will)f(run)h(on)h(most)h(commonly)f (used)g(computers)g(and)g(w)m(orkstations.)59 b(CFITSIO)35 b(supp)s(orts)f(all)i(the)0 3059 y(features)26 b(describ)s(ed)d(in)h (the)h(o\016cial)g(NOST)f(de\014nition)f(of)j(the)f(FITS)g(format)h (and)e(can)i(read)f(and)g(write)g(all)f(the)0 3172 y(curren)m(tly)d (de\014ned)f(t)m(yp)s(es)i(of)g(extensions,)h(including)18 b(ASCI)s(I)j(tables)g(\(T)-8 b(ABLE\),)23 b(Binary)e(tables)h(\(BINT)-8 b(ABLE\))0 3285 y(and)27 b(IMA)m(GE)h(extensions.)39 b(The)27 b(CFITSIO)f(routines)g(insulate)g(the)h(programmer)g(from)g (ha)m(ving)f(to)i(deal)f(with)0 3398 y(the)e(complicated)f(formatting)h (details)e(in)g(the)i(FITS)f(\014le,)h(ho)m(w)m(ev)m(er,)j(it)c(is)f (assumed)h(that)h(users)f(ha)m(v)m(e)i(a)f(general)0 3511 y(kno)m(wledge)30 b(ab)s(out)g(the)h(structure)f(and)g(usage)h(of) f(FITS)g(\014les.)0 3671 y(CFITSIO)k(also)i(con)m(tains)h(a)f(set)h(of) f(F)-8 b(ortran)36 b(callable)f(wrapp)s(er)g(routines)f(whic)m(h)h (allo)m(w)h(F)-8 b(ortran)36 b(programs)0 3784 y(to)31 b(call)e(the)h(CFITSIO)e(routines.)40 b(See)30 b(the)g(companion)f (\\FITSIO)g(User's)h(Guide")f(for)h(the)g(de\014nition)e(of)i(the)0 3897 y(F)-8 b(ortran)39 b(subroutine)c(calling)i(sequences.)63 b(These)38 b(wrapp)s(ers)e(replace)i(the)g(older)f(F)-8 b(ortran)39 b(FITSIO)d(library)0 4010 y(whic)m(h)29 b(is)h(no)g(longer) g(supp)s(orted.)0 4170 y(The)20 b(CFITSIO)f(pac)m(k)-5 b(age)23 b(w)m(as)e(initially)d(dev)m(elop)s(ed)i(b)m(y)g(the)h(HEASAR) m(C)g(\(High)g(Energy)f(Astroph)m(ysics)g(Science)0 4283 y(Arc)m(hiv)m(e)34 b(Researc)m(h)h(Cen)m(ter\))f(at)h(the)f(NASA)g(Go)s (ddard)e(Space)j(Fligh)m(t)e(Cen)m(ter)h(to)h(con)m(v)m(ert)g(v)-5 b(arious)33 b(existing)0 4396 y(and)25 b(newly)g(acquired)g (astronomical)h(data)g(sets)h(in)m(to)f(FITS)f(format)h(and)f(to)i (further)e(analyze)h(data)h(already)e(in)0 4509 y(FITS)i(format.)41 b(New)28 b(features)g(con)m(tin)m(ue)g(to)h(b)s(e)e(added)h(to)g (CFITSIO)f(in)f(large)i(part)g(due)g(to)g(con)m(tributions)f(of)0 4622 y(ideas)32 b(or)h(actual)g(co)s(de)g(from)f(users)g(of)h(the)g (pac)m(k)-5 b(age.)49 b(The)33 b(In)m(tegral)g(Science)f(Data)i(Cen)m (ter)f(in)f(Switzerland,)0 4734 y(and)h(the)g(XMM/ESTEC)h(pro)5 b(ject)34 b(in)e(The)h(Netherlands)f(made)h(esp)s(ecially)f (signi\014can)m(t)g(con)m(tributions)g(that)0 4847 y(resulted)d(in)g (man)m(y)i(of)f(the)h(new)f(features)g(that)h(app)s(eared)f(in)f(v2.0)j (of)e(CFITSIO.)0 5322 y Ff(1.2)135 b(Sources)45 b(of)g(FITS)f(Soft)l(w) l(are)i(and)f(Information)0 5601 y Fj(The)22 b(latest)h(v)m(ersion)f (of)h(the)f(CFITSIO)f(source)i(co)s(de,)h(do)s(cumen)m(tation,)h(and)c (example)i(programs)f(are)h(a)m(v)-5 b(ailable)0 5714 y(on)30 b(the)h(W)-8 b(orld-Wide)30 b(W)-8 b(eb)31 b(or)f(via)g(anon)m (ymous)g(ftp)g(from:)1927 5942 y(1)p eop %%Page: 2 10 2 9 bop 0 299 a Fj(2)2452 b Fh(CHAPTER)30 b(1.)71 b(INTR)m(ODUCTION)382 555 y Fe(http://heasarc.gsfc.nasa)o(.go)o(v/fi)o(tsio)382 668 y(ftp://legacy.gsfc.nasa.g)o(ov/)o(soft)o(ware)o(/fi)o(tsio)o(/c)0 902 y Fj(An)m(y)28 b(questions,)f(bug)g(rep)s(orts,)h(or)f(suggested)i (enhancemen)m(ts)f(related)f(to)i(the)e(CFITSIO)f(pac)m(k)-5 b(age)30 b(should)c(b)s(e)0 1015 y(sen)m(t)31 b(to)g(the)g(primary)d (author:)382 1249 y Fe(Dr.)47 b(William)f(Pence)810 b(Telephone:)92 b(\(301\))47 b(286-4599)382 1362 y(HEASARC,)e(Code)i(662)811 b(E-mail:)45 b(pence@tetra.gsfc.nasa.gov)382 1475 y(NASA/Goddard)f (Space)j(Flight)f(Center)382 1588 y(Greenbelt,)f(MD)i(20771,)f(USA)0 1822 y Fj(This)39 b(User's)j(Guide)e(assumes)h(that)h(readers)f (already)f(ha)m(v)m(e)j(a)f(general)f(understanding)d(of)k(the)f (de\014nition)0 1935 y(and)31 b(structure)g(of)h(FITS)e(format)i (\014les.)43 b(F)-8 b(urther)32 b(information)d(ab)s(out)j(FITS)f (formats)g(is)g(a)m(v)-5 b(ailable)31 b(from)g(the)0 2048 y(FITS)h(Supp)s(ort)f(O\016ce)i(at)g Fe(http://fits.gsfc.nasa.gov) o Fj(.)42 b(In)32 b(particular,)g(the)h('NOST)f(FITS)g(Standard')0 2161 y(giv)m(es)i(the)h(authoritativ)m(e)f(de\014nition)e(of)i(the)g (FITS)g(data)h(format,)g(and)f(the)g(`FITS)g(User's)g(Guide')f(pro)m (vides)0 2274 y(additional)28 b(historical)h(bac)m(kground)h(and)g (practical)g(advice)g(on)g(using)f(FITS)h(\014les.)0 2434 y(The)38 b(HEASAR)m(C)g(also)h(pro)m(vides)e(a)i(v)m(ery)g (sophisticated)f(FITS)f(\014le)h(analysis)f(program)h(called)g(`Fv')h (whic)m(h)0 2547 y(can)34 b(b)s(e)f(used)g(to)h(displa)m(y)e(and)h (edit)g(the)h(con)m(ten)m(ts)i(of)e(an)m(y)g(FITS)f(\014le)f(as)i(w)m (ell)f(as)h(construct)g(new)f(FITS)g(\014les)0 2660 y(from)j(scratc)m (h.)61 b(The)36 b(displa)m(y)f(functions)g(in)g(Fv)i(allo)m(w)f(users)g (to)i(in)m(teractiv)m(ely)e(adjust)g(the)h(brigh)m(tness)f(and)0 2773 y(con)m(trast)i(of)f(images,)h(pan,)g(zo)s(om,)h(and)d(blink)e (images,)39 b(and)d(measure)h(the)f(p)s(ositions)f(and)h(brigh)m (tnesses)g(of)0 2886 y(ob)5 b(jects)33 b(within)d(images.)46 b(FITS)31 b(tables)h(can)h(b)s(e)e(displa)m(y)m(ed)g(lik)m(e)h(a)g (spread)g(sheet,)h(and)f(then)f(mo)s(di\014ed)f(using)0 2999 y(p)s(o)m(w)m(erful)25 b(calculator)i(and)e(sorting)h(functions.) 38 b(Fv)27 b(is)e(freely)h(a)m(v)-5 b(ailable)26 b(for)g(most)h(Unix)e (platforms,)i(Mac)g(PCs,)0 3112 y(and)34 b(Windo)m(ws)f(PCs.)52 b(CFITSIO)33 b(users)h(ma)m(y)h(also)f(b)s(e)g(in)m(terested)h(in)e (the)h(FTOOLS)f(pac)m(k)-5 b(age)37 b(of)d(programs)0 3225 y(that)27 b(can)f(b)s(e)g(used)f(to)i(manipulate)e(and)g(analyze)i (FITS)e(format)i(\014les.)38 b(Fv)27 b(and)e(FTOOLS)g(are)i(a)m(v)-5 b(ailable)25 b(from)0 3337 y(their)k(resp)s(ectiv)m(e)i(W)-8 b(eb)31 b(sites)f(at:)382 3572 y Fe(http://fv.gsfc.nasa.gov)382 3685 y(http://heasarc.gsfc.nasa)o(.go)o(v/ft)o(ools)0 4014 y Ff(1.3)135 b(Ac)l(kno)l(wledgemen)l(ts)0 4264 y Fj(The)34 b(dev)m(elopmen)m(t)g(of)g(the)g(p)s(o)m(w)m(erful)f (features)h(in)f(CFITSIO)g(w)m(as)h(made)g(p)s(ossible)e(through)h (collab)s(orations)0 4377 y(with)d(man)m(y)h(p)s(eople)f(or)g (organizations)h(from)g(around)f(the)h(w)m(orld.)41 b(The)30 b(follo)m(wing)g(in)f(particular)h(ha)m(v)m(e)i(made)0 4490 y(esp)s(ecially)d(signi\014can)m(t)g(con)m(tributions:)0 4650 y(Programmers)c(from)h(the)f(In)m(tegral)h(Science)g(Data)h(Cen)m (ter,)g(Switzerland)d(\(namely)-8 b(,)27 b(Jurek)d(Bork)m(o)m(wski,)k (Bruce)0 4763 y(O'Neel,)33 b(and)f(Don)h(Jennings\),)e(designed)g(the)i (concept)g(for)f(the)h(plug-in)d(I/O)i(driv)m(ers)f(that)i(w)m(as)g(in) m(tro)s(duced)0 4876 y(with)h(CFITSIO)f(2.0.)56 b(The)34 b(use)h(of)g(`driv)m(ers')f(greatly)h(simpli\014ed)d(the)j(lo)m(w-lev)m (el)g(I/O,)g(whic)m(h)e(in)h(turn)g(made)0 4989 y(other)40 b(new)f(features)i(in)d(CFITSIO)g(\(e.g.,)45 b(supp)s(ort)38 b(for)h(compressed)h(FITS)f(\014les)g(and)g(supp)s(ort)f(for)i(IRAF)0 5102 y(format)32 b(image)f(\014les\))g(m)m(uc)m(h)g(easier)h(to)g (implemen)m(t.)42 b(Jurek)31 b(Bork)m(o)m(wski)g(wrote)h(the)g(Shared)e (Memory)i(driv)m(er,)0 5215 y(and)23 b(Bruce)i(O'Neel)f(wrote)g(the)g (driv)m(ers)f(for)g(accessing)i(FITS)e(\014les)g(o)m(v)m(er)i(the)f (net)m(w)m(ork)h(using)d(the)j(FTP)-8 b(,)24 b(HTTP)-8 b(,)0 5328 y(and)30 b(R)m(OOT)g(proto)s(cols.)0 5488 y(The)45 b(ISDC)g(also)g(pro)m(vided)f(the)i(template)g(parsing)e (routines)g(\(written)h(b)m(y)g(Jurek)g(Bork)m(o)m(wski\))h(and)f(the)0 5601 y(hierarc)m(hical)36 b(grouping)f(routines)h(\(written)h(b)m(y)g (Don)h(Jennings\).)59 b(The)37 b(ISDC)f(D)m(AL)i(\(Data)h(Access)f(La)m (y)m(er\))0 5714 y(routines)29 b(are)i(la)m(y)m(ered)g(on)f(top)h(of)f (CFITSIO)f(and)h(mak)m(e)h(extensiv)m(e)g(use)f(of)h(these)g(features.) p eop %%Page: 3 11 3 10 bop 0 299 a Fh(1.4.)72 b(LEGAL)30 b(STUFF)2995 b Fj(3)0 555 y(Uw)m(e)25 b(Lammers)e(\(XMM/ESA/ESTEC,)h(The)g (Netherlands\))f(designed)g(the)h(high-p)s(erformance)e(lexical)h (pars-)0 668 y(ing)41 b(algorithm)g(that)h(is)f(used)g(to)i(do)e (on-the-\015y)h(\014ltering)e(of)i(FITS)f(tables.)75 b(This)40 b(algorithm)h(essen)m(tially)0 781 y(pre-compiles)34 b(the)i(user-supplied)c(selection)k(expression)e(in)m(to)i(a)g(form)g (that)g(can)g(b)s(e)f(rapidly)e(ev)-5 b(aluated)36 b(for)0 894 y(eac)m(h)31 b(ro)m(w.)40 b(P)m(eter)31 b(Wilson)d(\(RSTX,)h (NASA/GSF)m(C\))i(then)e(wrote)h(the)g(parsing)e(routines)g(used)h(b)m (y)g(CFITSIO)0 1007 y(based)i(on)f(Lammers')h(design,)f(com)m(bined)g (with)g(other)h(tec)m(hniques)f(suc)m(h)h(as)g(the)g(CFITSIO)f (iterator)h(routine)0 1120 y(to)h(further)e(enhance)h(the)h(data)g(pro) s(cessing)e(throughput.)42 b(This)30 b(e\013ort)i(also)f(b)s (ene\014ted)f(from)h(a)h(m)m(uc)m(h)f(earlier)0 1233 y(lexical)22 b(parsing)h(routine)f(that)i(w)m(as)g(dev)m(elop)s(ed)f(b) m(y)h(Ken)m(t)g(Blac)m(kburn)e(\(NASA/GSF)m(C\).)j(More)g(recen)m(tly) -8 b(,)26 b(Craig)0 1346 y(Markw)m(ardt)j(\(NASA/GSF)m(C\))g(implemen)m (ted)e(additional)f(functions)h(\(median,)h(a)m(v)m(erage,)k(stddev\))c (and)g(other)0 1458 y(enhancemen)m(ts)j(to)g(the)g(lexical)e(parser.)0 1619 y(The)40 b(CFITSIO)g(iterator)h(function)e(is)h(lo)s(osely)g (based)h(on)f(similar)f(ideas)h(dev)m(elop)s(ed)g(for)h(the)g(XMM)g (Data)0 1732 y(Access)31 b(La)m(y)m(er.)0 1892 y(P)m(eter)25 b(Wilson)e(\(RSTX,)h(NASA/GSF)m(C\))h(wrote)g(the)f(complete)h(set)f (of)h(F)-8 b(ortran-callable)24 b(wrapp)s(ers)e(for)i(all)f(the)0 2005 y(CFITSIO)29 b(routines,)g(whic)m(h)g(in)g(turn)h(rely)f(on)i(the) f(CF)m(OR)-8 b(TRAN)31 b(macro)g(dev)m(elop)s(ed)f(b)m(y)g(Burkhard)f (Buro)m(w.)0 2165 y(The)h(syn)m(tax)i(used)e(b)m(y)h(CFITSIO)f(for)g (\014ltering)g(or)h(binning)c(input)i(FITS)i(\014les)f(is)g(based)g(on) h(ideas)g(dev)m(elop)s(ed)0 2278 y(for)41 b(the)g(AXAF)h(Science)f(Cen) m(ter)h(Data)h(Mo)s(del)d(b)m(y)h(Jonathan)g(McDo)m(w)m(ell,)k(An)m (tonella)c(F)-8 b(ruscione,)44 b(Aneta)0 2391 y(Siemigino)m(wsk)-5 b(a)24 b(and)h(Bill)f(Jo)m(y)m(e.)41 b(See)26 b(h)m (ttp://heasarc.gsfc.nasa.go)m(v/do)s(cs/journal/axaf7.h)m(t)q(ml)31 b(for)25 b(further)0 2503 y(description)j(of)j(the)g(AXAF)g(Data)h(Mo)s (del.)0 2664 y(The)j(\014le)f(decompression)g(co)s(de)h(w)m(ere)h(tak)m (en)g(directly)e(from)g(the)i(gzip)e(\(GNU)i(zip\))f(program)g(dev)m (elop)s(ed)f(b)m(y)0 2777 y(Jean-loup)29 b(Gailly)g(and)h(others.)0 2937 y(The)e(new)h(compressed)g(image)g(data)h(format)f(\(where)g(the)g (image)g(is)f(tiled)g(and)g(the)h(compressed)g(b)m(yte)h(stream)0 3050 y(from)k(eac)m(h)i(tile)f(is)e(stored)i(in)f(a)h(binary)e(table\)) j(w)m(as)f(implemen)m(ted)e(in)h(collab)s(oration)g(with)f(Ric)m(hard)h (White)0 3163 y(\(STScI\),)c(P)m(erry)g(Green\014eld)g(\(STScI\))g(and) f(Doug)i(T)-8 b(o)s(dy)30 b(\(NO)m(A)m(O\).)0 3323 y(Doug)h(Mink)f (\(SA)m(O\))g(pro)m(vided)f(the)i(routines)e(for)h(con)m(v)m(erting)i (IRAF)e(format)h(images)f(in)m(to)h(FITS)e(format.)0 3483 y(In)e(addition,)g(man)m(y)h(other)g(p)s(eople)f(ha)m(v)m(e)i (made)f(v)-5 b(aluable)27 b(con)m(tributions)f(to)j(the)f(dev)m (elopmen)m(t)g(of)g(CFITSIO.)0 3596 y(These)i(include)e(\(with)i(ap)s (ologies)g(to)h(others)f(that)h(ma)m(y)g(ha)m(v)m(e)h(inadv)m(erten)m (tly)e(b)s(een)f(omitted\):)0 3756 y(Stev)m(e)g(Allen,)e(Carl)g(Ak)m (erlof,)h(Keith)f(Arnaud,)h(Morten)g(Krabb)s(e)e(Barfo)s(ed,)j(Ken)m(t) f(Blac)m(kburn,)g(G)g(Bo)s(dammer,)0 3869 y(Romk)m(e)h(Bon)m(tek)m(o)s (e,)i(Lucio)c(Chiapp)s(etti,)f(Keith)h(Costorf,)h(Robin)f(Corb)s(et,)h (John)e(Da)m(vis,)j(Ric)m(hard)e(Fink,)h(Ning)0 3982 y(Gan,)j(Emily)d(Greene,)j(Gretc)m(hen)g(Green,)f(Jo)s(e)g(Harrington,) g(Cheng)g(Ho,)h(Phil)d(Ho)s(dge,)i(Jim)f(Ingham,)h(Y)-8 b(oshi-)0 4095 y(tak)j(a)44 b(Ishisaki,)g(Diab)f(Jerius,)h(Mark)g (Levine,)h(T)-8 b(o)s(dd)42 b(Karak)-5 b(askian,)46 b(Edw)m(ard)c (King,)j(Scott)f(Ko)s(c)m(h,)i(Claire)0 4208 y(Larkin,)c(Rob)f (Managan,)j(Eric)c(Mandel,)j(Ric)m(hard)d(Mathar,)k(John)c(Matto)m(x,) 46 b(Carsten)41 b(Mey)m(er,)k(Emi)39 b(Miy-)0 4320 y(ata,)44 b(Stefan)c(Mo)s(c)m(hnac)m(ki,)k(Mik)m(e)d(Noble,)h(Oliv)m(er)d(Ob)s (erdorf,)i(Cliv)m(e)e(P)m(age,)45 b(Arvind)38 b(P)m(armar,)43 b(Je\013)e(P)m(edelt)m(y)-8 b(,)0 4433 y(Tim)31 b(P)m(earson,)j (Philipp)s(e)28 b(Prugniel,)j(Maren)h(Purv)m(es,)h(Scott)g(Randall,)f (Chris)e(Rogers,)k(Arnold)c(Rots,)k(Barry)0 4546 y(Sc)m(hlesinger,)h (Robin)f(Stebbins,)h(Andrew)f(Szymk)m(o)m(wiak,)j(Allyn)c(T)-8 b(ennan)m(t,)37 b(P)m(eter)g(T)-8 b(eub)s(en,)35 b(James)h(Theiler,)0 4659 y(Doug)c(T)-8 b(o)s(dy)g(,)32 b(Shiro)e(Ueno,)j(Stev)m(e)f(W)-8 b(alton,)33 b(Arc)m(hie)f(W)-8 b(arno)s(c)m(k,)33 b(Alan)e(W)-8 b(atson,)33 b(Dan)f(Whipple,)e(Wim)h(Wim-)0 4772 y(mers,)f(P)m(eter)i (Y)-8 b(oung,)31 b(Jianjun)d(Xu,)i(and)g(Nelson)g(Zarate.)0 5216 y Ff(1.4)135 b(Legal)46 b(Stu\013)0 5488 y Fj(Cop)m(yrigh)m(t)36 b(\(Unpublished{all)d(righ)m(ts)j(reserv)m(ed)h(under)e(the)i(cop)m (yrigh)m(t)g(la)m(ws)f(of)h(the)g(United)f(States\),)k(U.S.)0 5601 y(Go)m(v)m(ernmen)m(t)30 b(as)g(represen)m(ted)e(b)m(y)h(the)g (Administrator)e(of)i(the)g(National)f(Aeronautics)h(and)f(Space)h (Adminis-)0 5714 y(tration.)41 b(No)31 b(cop)m(yrigh)m(t)f(is)g (claimed)f(in)g(the)i(United)e(States)i(under)e(Title)h(17,)h(U.S.)f (Co)s(de.)p eop %%Page: 4 12 4 11 bop 0 299 a Fj(4)2452 b Fh(CHAPTER)30 b(1.)71 b(INTR)m(ODUCTION)0 555 y Fj(P)m(ermission)28 b(to)i(freely)e(use,)i(cop)m(y)-8 b(,)31 b(mo)s(dify)-8 b(,)28 b(and)h(distribute)e(this)h(soft)m(w)m (are)j(and)e(its)g(do)s(cumen)m(tation)g(without)0 668 y(fee)g(is)e(hereb)m(y)h(gran)m(ted,)i(pro)m(vided)d(that)i(this)e(cop) m(yrigh)m(t)i(notice)f(and)g(disclaimer)e(of)i(w)m(arran)m(t)m(y)i(app) s(ears)d(in)g(all)0 781 y(copies.)41 b(\(Ho)m(w)m(ev)m(er,)33 b(see)e(the)f(restriction)f(on)i(the)f(use)g(of)h(the)f(gzip)g (compression)g(co)s(de,)h(b)s(elo)m(w\).)0 941 y(DISCLAIMER:)0 1101 y(THE)i(SOFTW)-10 b(ARE)32 b(IS)g(PR)m(O)m(VIDED)i('AS)f(IS')g (WITHOUT)f(ANY)i(W)-10 b(ARRANTY)33 b(OF)g(ANY)h(KIND,)f(EI-)0 1214 y(THER)42 b(EXPRESSED,)f(IMPLIED,)i(OR)e(ST)-8 b(A)g(TUTOR)g(Y,)43 b(INCLUDING,)f(BUT)h(NOT)e(LIMITED)h(TO,)0 1327 y(ANY)33 b(W)-10 b(ARRANTY)33 b(THA)-8 b(T)32 b(THE)g(SOFTW)-10 b(ARE)32 b(WILL)g(CONF)m(ORM)g(TO)g(SPECIFICA)-8 b(TIONS,)30 b(ANY)0 1440 y(IMPLIED)38 b(W)-10 b(ARRANTIES)37 b(OF)h(MER)m(CHANT)-8 b(ABILITY,)38 b(FITNESS)f(F)m(OR)h(A)g(P)-8 b(AR)g(TICULAR)38 b(PUR-)0 1553 y(POSE,)24 b(AND)i(FREEDOM)f(FR)m(OM)h(INFRINGEMENT,)g (AND)f(ANY)h(W)-10 b(ARRANTY)25 b(THA)-8 b(T)25 b(THE)g(DOC-)0 1666 y(UMENT)-8 b(A)g(TION)31 b(WILL)f(CONF)m(ORM)h(TO)e(THE)h(SOFTW) -10 b(ARE,)30 b(OR)g(ANY)h(W)-10 b(ARRANTY)31 b(THA)-8 b(T)30 b(THE)0 1779 y(SOFTW)-10 b(ARE)31 b(WILL)h(BE)g(ERR)m(OR)g (FREE.)g(IN)g(NO)f(EVENT)h(SHALL)f(NASA)h(BE)g(LIABLE)g(F)m(OR)g(ANY)0 1892 y(D)m(AMA)m(GES,)26 b(INCLUDING,)e(BUT)f(NOT)g(LIMITED)h(TO,)f (DIRECT,)g(INDIRECT,)g(SPECIAL)f(OR)h(CON-)0 2005 y(SEQUENTIAL)28 b(D)m(AMA)m(GES,)k(ARISING)d(OUT)g(OF,)h(RESUL)-8 b(TING)29 b(FR)m(OM,)h(OR)f(IN)h(ANY)g(W)-10 b(A)i(Y)30 b(CON-)0 2118 y(NECTED)25 b(WITH)g(THIS)f(SOFTW)-10 b(ARE,)25 b(WHETHER)g(OR)g(NOT)g(BASED)g(UPON)g(W)-10 b(ARRANTY,)26 b(CON-)0 2230 y(TRA)m(CT,)d(TOR)-8 b(T)23 b(,)g(OR)g(OTHER)-10 b(WISE,)22 b(WHETHER)i(OR)f(NOT)f(INJUR)-8 b(Y)24 b(W)-10 b(AS)23 b(SUST)-8 b(AINED)23 b(BY)h(PER-)0 2343 y(SONS)h(OR)i(PR)m (OPER)-8 b(TY)26 b(OR)g(OTHER)-10 b(WISE,)26 b(AND)h(WHETHER)g(OR)f (NOT)g(LOSS)f(W)-10 b(AS)26 b(SUST)-8 b(AINED)0 2456 y(FR)m(OM,)37 b(OR)e(AR)m(OSE)h(OUT)f(OF)h(THE)g(RESUL)-8 b(TS)35 b(OF,)h(OR)f(USE)h(OF,)g(THE)g(SOFTW)-10 b(ARE)35 b(OR)g(SER-)0 2569 y(VICES)29 b(PR)m(O)m(VIDED)j(HEREUNDER.")0 2729 y(The)i(\014le)h(compress.c)g(con)m(tains)g(\(sligh)m(tly)f(mo)s (di\014ed\))f(source)i(co)s(de)g(that)h(originally)c(came)k(from)f (gzip-1.2.4,)0 2842 y(cop)m(yrigh)m(t)26 b(\(C\))g(1992-1993)k(b)m(y)c (Jean-loup)f(Gailly)-8 b(.)38 b(This)24 b(gzip)h(co)s(de)h(is)f (distributed)e(under)i(the)h(GNU)g(General)0 2955 y(Public)k(License)i (and)f(th)m(us)h(requires)f(that)i(an)m(y)f(soft)m(w)m(are)i(that)f (uses)f(the)g(CFITSIO)f(library)f(\(whic)m(h)h(in)g(turn)0 3068 y(uses)e(the)g(gzip)g(co)s(de\))h(m)m(ust)f(conform)g(to)h(the)f (pro)m(visions)e(in)h(the)i(GNU)g(General)f(Public)e(License.)40 b(A)29 b(cop)m(y)h(of)0 3181 y(the)h(GNU)g(license)e(is)g(included)f (at)j(the)g(b)s(eginning)c(of)k(compress.c)g(\014le.)0 3341 y(An)h(alternate)i(v)m(ersion)e(of)h(the)g(compress.c)g(\014le)f (\(called)g(compress)p 2381 3341 28 4 v 33 w(alternate.c\))i(is)e(pro)m (vided)f(for)i(users)e(who)0 3454 y(w)m(an)m(t)24 b(to)g(use)e(the)i (CFITSIO)d(library)g(but)h(are)h(un)m(willing)d(or)j(unable)e(to)j (publicly)c(release)j(their)f(soft)m(w)m(are)i(under)0 3567 y(the)i(terms)g(of)g(the)g(GNU)h(General)e(Public)f(License.)39 b(This)24 b(alternate)i(v)m(ersion)g(con)m(tains)g(non-functional)e (stubs)0 3680 y(for)g(the)h(\014le)e(compression)h(and)f(uncompression) g(routines)g(used)h(b)m(y)g(CFITSIO.)f(Replace)i(the)f(\014le)g (`compress.c')0 3793 y(with)32 b(`compress)p 600 3793 V 33 w(alternate.c')j(b)s(efore)e(compiling)e(the)i(CFITSIO)f(library) -8 b(.)48 b(This)31 b(will)g(pro)s(duce)h(a)i(v)m(ersion)f(of)0 3906 y(CFITSIO)20 b(whic)m(h)h(do)s(es)g(not)h(supp)s(ort)e(reading)h (or)h(writing)e(compressed)h(FITS)g(\014les)g(but)g(is)g(otherwise)g (iden)m(tical)0 4019 y(to)31 b(the)g(standard)e(v)m(ersion.)p eop %%Page: 5 13 5 12 bop 0 1225 a Fg(Chapter)65 b(2)0 1687 y Fm(Creating)77 b(the)h(CFITSIO)e(Library)0 2216 y Ff(2.1)135 b(Building)45 b(the)h(Library)0 2466 y Fj(The)h(CFITSIO)f(co)s(de)h(is)g(con)m (tained)g(in)f(ab)s(out)h(40)h(C)f(source)h(\014les)e(\(*.c\))j(and)e (header)g(\014les)f(\(*.h\).)93 b(On)0 2579 y(V)-10 b(AX/VMS)31 b(systems)g(2)f(assem)m(bly-co)s(de)h(\014les)e(\(vmsieeed.mar)h(and)g (vmsieeer.mar\))h(are)f(also)h(needed.)0 2739 y(CFITSIO)e(has)h(curren) m(tly)f(b)s(een)h(tested)h(on)f(the)h(follo)m(wing)e(platforms:)95 2959 y Fe(OPERATING)46 b(SYSTEM)523 b(COMPILER)143 3072 y(Sun)47 b(OS)1002 b(gcc)47 b(and)g(cc)g(\(3.0.1\))143 3185 y(Sun)g(Solaris)762 b(gcc)47 b(and)g(cc)143 3298 y(Silicon)f(Graphics)g(IRIX)285 b(gcc)47 b(and)g(cc)143 3411 y(Silicon)f(Graphics)g(IRIX64)189 b(MIPS)143 3523 y(Dec)47 b(Alpha)f(OSF/1)572 b(gcc)47 b(and)g(cc)143 3636 y(DECstation)93 b(Ultrix)428 b(gcc)143 3749 y(Dec)47 b(Alpha)f(OpenVMS)476 b(cc)143 3862 y(DEC)47 b(VAX/VMS)762 b(gcc)47 b(and)g(cc)143 3975 y(HP-UX)1049 b(gcc)143 4088 y(IBM)47 b(AIX)954 b(gcc)143 4201 y(Linux)1049 b(gcc)143 4314 y(MkLinux)953 b(DR3)143 4427 y(Windows)46 b(95/98/NT)523 b(Borland)46 b(C++)h(V4.5)143 4540 y(Windows)f(95/98/NT/ME/XP)235 b(Microsoft/Compaq)43 b(Visual)j(C++)h(v5.0,)g(v6.0)143 4653 y(Windows)f(95/98/NT)523 b(Cygwin)46 b(gcc)143 4765 y(MacOS)h(7.1)f(or)i(greater)332 b(Metrowerks)45 b(10.+)143 4878 y(MacOS-X)h(10.1)h(or)g(greater)189 b(cc)47 b(\(gcc\))0 5098 y Fj(CFITSIO)26 b(will)g(probably)g(run)g(on)i(most)g(other)h (Unix)d(platforms.)39 b(Cra)m(y)28 b(sup)s(ercomputers)e(are)j(curren)m (tly)e(not)0 5211 y(supp)s(orted.)0 5495 y Fd(2.1.1)112 b(Unix)38 b(Systems)0 5714 y Fj(The)30 b(CFITSIO)f(library)f(is)h (built)f(on)j(Unix)e(systems)h(b)m(y)g(t)m(yping:)1927 5942 y(5)p eop %%Page: 6 14 6 13 bop 0 299 a Fj(6)1580 b Fh(CHAPTER)30 b(2.)112 b(CREA)-8 b(TING)30 b(THE)g(CFITSIO)f(LIBRAR)-8 b(Y)48 555 y Fe(>)95 b(./configure)45 b([--prefix=/target/insta)o(llat)o(ion)o(/pat)o(h])48 668 y(>)95 b(make)476 b(\(or)95 b('make)46 b(shared'\))48 781 y(>)95 b(make)47 b(install)93 b(\(this)46 b(step)h(is)g(optional\)) 0 1037 y Fj(at)24 b(the)g(op)s(erating)f(system)h(prompt.)38 b(The)23 b(con\014gure)g(command)g(customizes)h(the)g(Mak)m(e\014le)g (for)g(the)g(particular)0 1150 y(system,)g(then)d(the)g(`mak)m(e')i (command)e(compiles)f(the)h(source)h(\014les)e(and)h(builds)d(the)j (library)-8 b(.)36 b(T)m(yp)s(e)21 b(`./con\014gure')0 1263 y(and)34 b(not)h(simply)d(`con\014gure')j(to)h(ensure)e(that)h (the)g(con\014gure)g(script)e(in)h(the)h(curren)m(t)f(directory)g(is)g (run)g(and)0 1375 y(not)29 b(some)g(other)g(system-wide)f(con\014gure)g (script.)39 b(The)29 b(optional)f('pre\014x')g(argumen)m(t)h(to)g (con\014gure)g(giv)m(es)g(the)0 1488 y(path)f(to)i(the)f(directory)f (where)g(the)h(CFITSIO)f(library)e(and)i(include)f(\014les)g(should)g (b)s(e)h(installed)f(via)h(the)h(later)0 1601 y('mak)m(e)j(install')c (command.)41 b(F)-8 b(or)31 b(example,)143 1857 y Fe(>)48 b(./configure)c(--prefix=/usr1/local)0 2113 y Fj(will)22 b(cause)k(the)f('mak)m(e)h(install')d(command)i(to)h(cop)m(y)g(the)f (CFITSIO)e(lib)s(c\014tsio)f(\014le)j(to)g(/usr1/lo)s(cal/lib)e(and)i (the)0 2226 y(necessary)33 b(include)c(\014les)j(to)g(/usr1/lo)s (cal/include)f(\(assuming)g(of)h(course)g(that)h(the)f(pro)s(cess)g (has)g(p)s(ermission)0 2338 y(to)f(write)f(to)h(these)g(directories\).) 0 2499 y(The)d('mak)m(e)h(shared')f(option)g(builds)d(a)k(shared)e(or)i (dynamic)e(v)m(ersion)h(of)g(the)h(CFITSIO)d(library)-8 b(.)38 b(When)28 b(using)0 2612 y(the)f(shared)f(library)f(the)i (executable)g(co)s(de)g(is)f(not)h(copied)f(in)m(to)h(y)m(our)g (program)g(at)g(link)e(time)h(and)h(instead)f(the)0 2724 y(program)h(lo)s(cates)h(the)g(necessary)g(library)d(co)s(de)j(at)g (run)e(time,)i(normally)e(through)g(LD)p 3065 2724 28 4 v 33 w(LIBRAR)-8 b(Y)p 3514 2724 V 34 w(P)g(A)g(TH)28 b(or)0 2837 y(some)j(other)f(metho)s(d.)41 b(The)29 b(adv)-5 b(an)m(tages)33 b(of)d(using)f(a)i(shared)e(library)f(are:)143 3093 y Fe(1.)95 b(Less)47 b(disk)f(space)h(if)g(you)g(build)f(more)h (than)f(1)i(program)143 3206 y(2.)95 b(Less)47 b(memory)f(if)h(more)g (than)f(one)h(copy)g(of)g(a)g(program)f(using)h(the)g(shared)334 3319 y(library)f(is)h(running)f(at)h(the)g(same)g(time)f(since)h(the)g (system)f(is)h(smart)334 3432 y(enough)f(to)h(share)g(copies)f(of)h (the)g(shared)f(library)g(at)h(run)g(time.)143 3545 y(3.)95 b(Possibly)46 b(easier)g(maintenance)e(since)j(a)g(new)g(version)f(of)h (the)g(shared)334 3658 y(library)f(can)h(be)g(installed)e(without)h (relinking)f(all)i(the)g(software)334 3770 y(that)g(uses)f(it)i(\(as)e (long)h(as)g(the)g(subroutine)e(names)i(and)f(calling)334 3883 y(sequences)f(remain)h(unchanged\).)143 3996 y(4.)95 b(No)47 b(run-time)f(penalty.)0 4252 y Fj(The)30 b(disadv)-5 b(an)m(tages)31 b(are:)143 4508 y Fe(1.)47 b(More)g(hassle)f(at)h (runtime.)94 b(You)46 b(have)h(to)g(either)f(build)h(the)g(programs)286 4621 y(specially)f(or)h(have)f(LD_LIBRARY_PATH)e(set)j(right.)143 4733 y(2.)g(There)g(may)g(be)g(a)g(slight)f(start)h(up)g(penalty,)e (depending)h(on)h(where)f(you)h(are)286 4846 y(reading)f(the)h(shared)f (library)g(and)h(the)g(program)f(from)g(and)h(if)g(your)g(CPU)g(is)286 4959 y(either)f(really)h(slow)f(or)h(really)f(heavily)g(loaded.)0 5215 y Fj(On)32 b(Mac)i(OS)e(X)i(platforms)e(the)h('mak)m(e)h(shared')f (command)f(w)m(orks)h(lik)m(e)g(on)g(other)g(UNIX)g(platforms,)g(but)g (a)0 5328 y(.dylib)d(\014le)h(will)e(b)s(e)i(created)i(instead)f(of)g (.so.)46 b(If)31 b(installed)f(in)h(a)h(nonstandard)f(lo)s(cation,)h (add)f(its)h(lo)s(cation)f(to)0 5441 y(the)g(D)m(YLD)p 422 5441 V 34 w(LIBRAR)-8 b(Y)p 872 5441 V 33 w(P)g(A)g(TH)31 b(en)m(vironmen)m(t)f(v)-5 b(ariable)29 b(so)i(that)g(the)f(library)e (can)j(b)s(e)f(found)f(at)i(run)e(time.)0 5601 y(On)h(HP/UX)i(systems,) g(the)f(en)m(vironmen)m(t)g(v)-5 b(ariable)30 b(CFLA)m(GS)h(should)e(b) s(e)i(set)g(to)h(-Ae)g(b)s(efore)f(running)d(con-)0 5714 y(\014gure)i(to)h(enable)f("extended)h(ANSI")f(features.)p eop %%Page: 7 15 7 14 bop 0 299 a Fh(2.1.)72 b(BUILDING)31 b(THE)f(LIBRAR)-8 b(Y)2507 b Fj(7)0 555 y(By)31 b(default,)g(a)g(set)h(of)f(F)-8 b(ortran-callable)31 b(wrapp)s(er)e(routines)h(are)h(also)g(built)e (and)h(included)f(in)g(the)i(CFITSIO)0 668 y(library)-8 b(.)68 b(If)40 b(these)g(wrapp)s(er)f(routines)g(are)h(not)h(needed)e (\(i.e.,)44 b(the)c(CFITSIO)f(library)e(will)h(not)i(b)s(e)g(link)m(ed) 0 781 y(to)d(an)m(y)f(F)-8 b(ortran)37 b(applications)d(whic)m(h)h (call)g(FITSIO)g(subroutines\))f(then)i(they)g(ma)m(y)h(b)s(e)e (omitted)h(from)g(the)0 894 y(build)26 b(b)m(y)k(t)m(yping)f('mak)m(e)h (all-no\014tsio')f(instead)f(of)i(simply)d(t)m(yping)i('mak)m(e'.)42 b(This)27 b(will)g(reduce)i(the)h(size)f(of)h(the)0 1007 y(CFITSIO)f(library)f(sligh)m(tly)-8 b(.)0 1167 y(Most)37 b(32-bit)g(op)s(erating)f(systems)g(ha)m(v)m(e)i(only)d(supp)s(orted)g (disk)g(\014les)g(up)g(to)i(2.1GB)i(\(2**31)g(b)m(ytes\))e(in)e(size.)0 1280 y(Starting)c(with)f(v)m(ersion)h(2.1)h(of)g(CFITSIO,)e(FITS)h (\014les)f(larger)h(than)g(this)g(limit)e(\(up)i(to)h(6)g(terab)m (ytes\))h(can)f(b)s(e)0 1393 y(read)25 b(and)g(written)f(on)h (platforms)f(that)h(supp)s(ort)f(large)h(\014les)f(\(e.g.,)k(at)e (least)f(some)h(LINUX)f(platforms)f(and)h(So-)0 1506 y(laris\).)36 b(T)-8 b(o)22 b(enable)e(this)g(feature,)j(CFITSIO)d(m)m (ust)h(b)s(e)f(compiled)f(with)h(the)h('-D)p 2731 1506 28 4 v 34 w(LAR)m(GEFILE)p 3298 1506 V 33 w(SOUR)m(CE')g(and)0 1619 y(`-D)p 129 1619 V 34 w(FILE)p 374 1619 V 32 w(OFFSET)p 774 1619 V 32 w(BITS=64')g(compiler)e(\015ags.)37 b(Some)21 b(platforms)e(ma)m(y)i(also)f(require)f(the)h(`-D)p 3380 1619 V 34 w(LAR)m(GE)p 3736 1619 V 33 w(FILES')0 1732 y(compiler)29 b(\015ag.)42 b(It)30 b(app)s(ears)g(that)h(in)e(most)i (cases)g(it)g(is)e(not)i(necessary)g(to)g(also)f(include)f(these)i (compiler)e(\015ags)0 1844 y(when)k(compiling)f(programs)h(that)i(link) d(to)i(the)g(CFITSIO)f(library)-8 b(.)49 b(See)34 b(the)g(`CFITSIO)f (Size)g(Limitations')0 1957 y(section)e(in)e(Chapter)g(4)i(for)f (further)f(details.)0 2118 y(It)g(ma)m(y)h(not)f(b)s(e)f(p)s(ossible)f (to)i(staticly)g(link)e(programs)i(that)g(use)g(CFITSIO)e(on)i(some)h (platforms)d(\(namely)-8 b(,)30 b(on)0 2230 y(Solaris)k(2.6\))j(due)e (to)i(the)e(net)m(w)m(ork)i(driv)m(ers)d(\(whic)m(h)h(pro)m(vide)g(FTP) g(and)g(HTTP)g(access)i(to)g(FITS)e(\014les\).)56 b(It)0 2343 y(is)32 b(p)s(ossible)e(to)k(mak)m(e)f(b)s(oth)g(a)g(dynamic)e (and)h(a)i(static)f(v)m(ersion)f(of)h(the)g(CFITSIO)e(library)-8 b(,)32 b(but)g(net)m(w)m(ork)i(\014le)0 2456 y(access)e(will)27 b(not)k(b)s(e)f(p)s(ossible)e(using)h(the)h(static)h(v)m(ersion.)0 2762 y Fd(2.1.2)112 b(VMS)0 2984 y Fj(On)28 b(V)-10 b(AX/VMS)31 b(and)d(ALPHA/VMS)i(systems)f(the)h(mak)m(e)p 2100 2984 V 34 w(g\015oat.com)h(command)e(\014le)f(ma)m(y)i(b)s(e)f(executed)h (to)0 3097 y(build)j(the)k(c\014tsio.olb)e(ob)5 b(ject)37 b(library)d(using)h(the)h(default)g(G-\015oating)g(p)s(oin)m(t)g (option)f(for)h(double)f(v)-5 b(ariables.)0 3210 y(The)37 b(mak)m(e)p 405 3210 V 33 w(d\015oat.com)i(and)d(mak)m(e)p 1279 3210 V 34 w(ieee.com)i(\014les)f(ma)m(y)g(b)s(e)g(used)f(instead)h (to)h(build)c(the)j(library)e(with)h(the)0 3322 y(other)26 b(\015oating)h(p)s(oin)m(t)e(options.)38 b(Note)28 b(that)f(the)f (getcwd)h(function)e(that)i(is)e(used)g(in)g(the)i(group.c)f(mo)s(dule) e(ma)m(y)0 3435 y(require)43 b(that)j(programs)e(using)f(CFITSIO)g(b)s (e)h(link)m(ed)g(with)f(the)i(ALPHA$LIBRAR)-8 b(Y:V)e(AX)m(CR)i(TL.OLB) 0 3548 y(library)g(.)39 b(See)30 b(the)h(example)f(link)e(line)h(in)g (the)i(next)f(section)h(of)f(this)g(do)s(cumen)m(t.)0 3854 y Fd(2.1.3)112 b(Windo)m(ws)37 b(PCs)0 4076 y Fj(A)28 b(precompiled)e(DLL)i(v)m(ersion)f(of)h(CFITSIO)e(is)h(a)m(v)-5 b(ailable)28 b(for)f(IBM-PC)h(users)g(of)g(the)g(Borland)f(or)h (Microsoft)0 4189 y(Visual)44 b(C++)g(compilers)g(in)g(the)i(\014les)e (c\014tsio)s(dll)p 1802 4189 V 31 w(2xxx)p 2022 4189 V 33 w(b)s(orland.zip)e(and)j(c\014tsio)s(dll)p 3078 4189 V 30 w(2xxx)p 3297 4189 V 33 w(v)m(cc.zip,)50 b(where)0 4302 y('2xxx')45 b(represen)m(ts)f(the)g(curren)m(t)g(release)h(n)m(um) m(b)s(er.)81 b(These)44 b(zip)f(arc)m(hiv)m(es)h(also)h(con)m(tains)f (other)g(\014les)g(and)0 4414 y(instructions)28 b(on)i(ho)m(w)h(to)g (use)f(the)h(CFITSIO)d(DLL)j(library)-8 b(.)0 4575 y(The)28 b(CFITSIO)g(library)e(ma)m(y)j(also)g(b)s(e)f(built)f(from)h(the)h (source)g(co)s(de)g(using)f(the)h(mak)m(e\014le.b)s(c)f(or)h(mak)m (e\014le.v)m(cc)0 4688 y(\014les.)54 b(Finally)-8 b(,)35 b(the)g(mak)m(ep)s(c.bat)h(\014le)e(giv)m(es)i(an)f(example)g(of)g (building)c(CFITSIO)j(with)f(the)j(Borland)e(C++)0 4800 y(v4.5)d(compiler)e(using)g(older)h(DOS)g(commands.)0 5106 y Fd(2.1.4)112 b(Macin)m(tosh)38 b(PCs)0 5328 y Fj(When)30 b(building)d(on)j(Mac)h(OS-X,)g(users)e(should)g(follo)m(w)g (the)i(Unix)e(instructions,)f(ab)s(o)m(v)m(e.)0 5488 y(The)h(classic)f(MacOS)h(v)m(ersion)g(\(OS)g(9)g(or)g(earlier\))f(of)i (the)f(CFITSIO)e(library)g(can)i(b)s(e)g(built)e(b)m(y)i(\(1\))h(un)e (binhex)0 5601 y(and)e(unstu\013)g(c\014tsio)p 714 5601 V 33 w(mac.sit.hqx,)i(\(2\))g(put)e(CFitsioPPC.mcp)f(in)h(the)h (c\014tsio)g(directory)-8 b(,)28 b(and)e(\(3\))i(load)f(CFit-)0 5714 y(sioPPC.mcp)i(in)m(to)i(Co)s(deW)-8 b(arrior)30 b(Pro)g(5)h(and)f(mak)m(e.)42 b(This)29 b(builds)e(the)k(CFITSIO)e (library)f(for)i(PPC.)g(There)p eop %%Page: 8 16 8 15 bop 0 299 a Fj(8)1580 b Fh(CHAPTER)30 b(2.)112 b(CREA)-8 b(TING)30 b(THE)g(CFITSIO)f(LIBRAR)-8 b(Y)0 555 y Fj(are)31 b(also)f(targets)i(for)e(b)s(oth)g(the)g(test)i(program)e(and)f(the)i (sp)s(eed)e(test)j(program.)0 715 y(T)-8 b(o)27 b(use)f(the)h(MacOS)g (p)s(ort)f(y)m(ou)h(can)g(add)f(C\014tsio)g(PPC.lib)e(to)j(y)m(our)g (Co)s(deW)-8 b(arrior)26 b(Pro)g(5)h(pro)5 b(ject.)40 b(Note)28 b(that)0 828 y(this)h(only)h(has)g(b)s(een)g(tested)h(for)f (the)g(PPC)g(and)g(probably)e(w)m(on't)j(w)m(ork)g(on)f(68k)h(Macs.)0 1162 y Ff(2.2)135 b(T)-11 b(esting)46 b(the)f(Library)0 1412 y Fj(The)40 b(CFITSIO)e(library)g(should)g(b)s(e)h(tested)i(b)m(y) f(building)c(and)j(running)f(the)i(testprog.c)h(program)f(that)h(is)0 1525 y(included)28 b(with)h(the)h(release.)41 b(On)30 b(Unix)f(systems,)i(t)m(yp)s(e:)191 1782 y Fe(\045)47 b(make)g(testprog)191 1895 y(\045)g(testprog)f(>)h(testprog.lis)191 2008 y(\045)g(diff)g(testprog.lis)d(testprog.out)191 2121 y(\045)j(cmp)g(testprog.fit)e(testprog.std)0 2378 y Fj(On)30 b(VMS)g(systems,)g(\(assuming)g(cc)h(is)e(the)i(name)f(of)h (the)f(C)g(compiler)f(command\),)i(t)m(yp)s(e:)191 2636 y Fe($)47 b(cc)h(testprog.c)191 2749 y($)f(link)g(testprog,)e (cfitsio/lib,)g(alpha$library:vaxcrtl/l)o(ib)191 2862 y($)i(run)g(testprog)0 3119 y Fj(The)42 b(test)h(program)f(should)e (pro)s(duce)h(a)i(FITS)e(\014le)h(called)f(`testprog.\014t')j(that)f (is)e(iden)m(tical)g(to)i(the)f(`test-)0 3232 y(prog.std')35 b(FITS)e(\014le)h(included)d(with)i(this)g(release.)53 b(The)34 b(diagnostic)g(messages)h(\(whic)m(h)f(w)m(ere)h(pip)s(ed)d (to)j(the)0 3345 y(\014le)g(testprog.lis)h(in)f(the)i(Unix)e(example\)) h(should)e(b)s(e)i(iden)m(tical)f(to)i(the)f(listing)e(con)m(tained)j (in)e(the)h(\014le)g(test-)0 3458 y(prog.out.)63 b(The)37 b('di\013)7 b(')37 b(and)g('cmp')h(commands)g(sho)m(wn)f(ab)s(o)m(v)m (e)i(should)c(not)j(rep)s(ort)f(an)m(y)h(di\013erences)f(in)g(the)0 3571 y(\014les.)64 b(\(There)38 b(ma)m(y)h(b)s(e)f(some)h(minor)e (format)i(di\013erences,)h(suc)m(h)e(as)h(the)g(presence)f(or)h (absence)g(of)f(leading)0 3684 y(zeros,)31 b(or)g(3)f(digit)g(exp)s (onen)m(ts)g(in)f(n)m(um)m(b)s(ers,)g(whic)m(h)g(can)i(b)s(e)f (ignored\).)0 3844 y(The)e(F)-8 b(ortran)30 b(wrapp)s(ers)d(in)g (CFITSIO)g(ma)m(y)j(b)s(e)e(tested)h(with)f(the)h(testf77)h(program)f (on)g(Unix)e(systems)i(with:)191 4101 y Fe(\045)47 b(f77)g(-o)g (testf77)f(testf77.f)g(-L.)g(-lcfitsio)g(-lnsl)g(-lsocket)95 4214 y(or)191 4327 y(\045)h(f77)g(-f)g(-o)h(testf77)d(testf77.f)h(-L.)h (-lcfitsio)188 b(\(under)46 b(SUN)h(O/S\))95 4440 y(or)191 4553 y(\045)g(f77)g(-o)g(testf77)f(testf77.f)g(-Wl,-L.)f(-lcfitsio)h (-lm)h(-lnsl)f(-lsocket)f(\(HP/UX\))191 4779 y(\045)i(testf77)f(>)i (testf77.lis)191 4892 y(\045)f(diff)g(testf77.lis)e(testf77.out)191 5005 y(\045)i(cmp)g(testf77.fit)e(testf77.std)0 5262 y Fj(On)31 b(mac)m(hines)g(running)f(SUN)h(O/S,)h(F)-8 b(ortran)33 b(programs)e(m)m(ust)h(b)s(e)f(compiled)f(with)h(the)h('-f) 7 b(')32 b(option)g(to)g(force)0 5375 y(double)24 b(precision)g(v)-5 b(ariables)24 b(to)i(b)s(e)f(aligned)f(on)i(8-b)m(yte)h(b)s(oundarys)c (to)j(mak)m(e)h(the)e(fortran-declared)g(v)-5 b(ariables)0 5488 y(compatible)32 b(with)f(C.)h(A)h(similar)d(compiler)h(option)h (ma)m(y)h(b)s(e)f(required)f(on)h(other)h(platforms.)47 b(F)-8 b(ailing)31 b(to)i(use)0 5601 y(this)25 b(option)g(ma)m(y)h (cause)h(the)f(program)f(to)i(crash)e(on)h(FITSIO)f(routines)f(that)j (read)f(or)f(write)g(double)g(precision)0 5714 y(v)-5 b(ariables.)p eop %%Page: 9 17 9 16 bop 0 299 a Fh(2.3.)72 b(LINKING)30 b(PR)m(OGRAMS)h(WITH)f (CFITSIO)1975 b Fj(9)0 555 y(Also)30 b(note)h(that)f(on)g(some)h (systems,)f(the)h(output)e(listing)f(of)j(the)f(testf77)i(program)d(ma) m(y)i(di\013er)e(sligh)m(tly)f(from)0 668 y(the)j(testf77.std)h (template,)f(if)f(leading)f(zeros)i(are)g(not)g(prin)m(ted)e(b)m(y)i (default)f(b)s(efore)g(the)h(decimal)e(p)s(oin)m(t)h(when)0 781 y(using)f(F)i(format.)0 941 y(A)37 b(few)f(other)g(utilit)m(y)f (programs)h(are)h(included)d(with)h(CFITSIO;)g(the)i(\014rst)e(four)h (of)g(this)g(programs)g(can)h(b)s(e)0 1054 y(compiled)c(an)i(link)m(ed) e(b)m(y)i(t)m(yping)f(`mak)m(e)i(program)p 1815 1054 28 4 v 33 w(name')f(where)f(`program)p 2746 1054 V 33 w(name')h(is)f(the)h(actual)g(name)g(of)0 1167 y(the)c(program:)191 1467 y Fe(speed)46 b(-)i(measures)d(the)i(maximum)f(throughput)f(\(in)i (MB)g(per)g(second\))668 1580 y(for)g(writing)f(and)h(reading)f(FITS)g (files)h(with)f(CFITSIO.)191 1806 y(listhead)f(-)j(lists)e(all)h(the)g (header)f(keywords)g(in)h(any)g(FITS)f(file)191 2032 y(fitscopy)f(-)j(copies)e(any)h(FITS)g(file)f(\(especially)f(useful)h (in)h(conjunction)811 2145 y(with)g(the)g(CFITSIO's)e(extended)h(input) g(filename)g(syntax\).)191 2371 y(cookbook)f(-)j(a)f(sample)f(program)g (that)h(performs)e(common)i(read)f(and)811 2483 y(write)h(operations)e (on)i(a)g(FITS)g(file.)191 2709 y(iter_a,)f(iter_b,)g(iter_c)g(-)h (examples)f(of)h(the)g(CFITSIO)f(iterator)f(routine)0 3091 y Ff(2.3)135 b(Linking)45 b(Programs)h(with)f(CFITSIO)0 3350 y Fj(When)25 b(linking)e(applications)h(soft)m(w)m(are)j(with)d (the)i(CFITSIO)e(library)-8 b(,)25 b(sev)m(eral)h(system)g(libraries)d (usually)g(need)0 3463 y(to)36 b(b)s(e)f(sp)s(eci\014ed)f(on)h(the)g (link)f(command)h(line.)54 b(On)34 b(Unix)h(systems,)i(the)e(most)h (reliable)d(w)m(a)m(y)k(to)f(determine)0 3576 y(what)26 b(libraries)e(are)i(required)f(is)g(to)i(t)m(yp)s(e)f('mak)m(e)i (testprog')f(and)f(see)h(what)f(libraries)e(the)i(con\014gure)g(script) f(has)0 3689 y(added.)39 b(The)25 b(t)m(ypical)h(libraries)d(that)j (need)g(to)g(b)s(e)g(added)f(are)h(-lm)g(\(the)g(math)g(library\))e (and)h(-lnsl)f(and)i(-lso)s(c)m(k)m(et)0 3802 y(\(needed)k(only)f(for)h (FTP)g(and)f(HTTP)g(\014le)g(access\).)43 b(These)30 b(latter)g(2)g(libraries)d(are)k(not)f(needed)g(on)g(VMS)g(and)0 3915 y(Windo)m(ws)f(platforms,)h(b)s(ecause)g(FTP)h(\014le)e(access)j (is)d(not)i(curren)m(tly)e(supp)s(orted)g(on)h(those)h(platforms.)0 4075 y(Note)i(that)g(when)e(upgrading)f(to)j(a)f(new)m(er)g(v)m(ersion) f(of)h(CFITSIO)f(it)g(is)g(usually)f(necessary)i(to)h(recompile,)f(as)0 4188 y(w)m(ell)d(as)i(relink,)e(the)h(programs)g(that)h(use)f(CFITSIO,) f(b)s(ecause)i(the)f(de\014nitions)e(in)h(\014tsio.h)h(often)g(c)m (hange.)0 4569 y Ff(2.4)135 b(Getting)46 b(Started)g(with)f(CFITSIO)0 4829 y Fj(In)27 b(order)h(to)g(e\013ectiv)m(ely)h(use)f(the)g(CFITSIO)e (library)g(it)h(is)g(recommended)h(that)g(new)f(users)h(b)s(egin)e(b)m (y)i(reading)0 4942 y(the)g(\\CFITSIO)g(Quic)m(k)f(Start)h(Guide".)40 b(It)28 b(con)m(tains)g(all)g(the)g(basic)g(information)e(needed)i(to)h (write)e(programs)0 5055 y(that)d(p)s(erform)f(most)h(t)m(yp)s(es)g(of) g(op)s(erations)f(on)h(FITS)f(\014les.)38 b(The)23 b(set)i(of)f (example)f(FITS)h(utilit)m(y)e(programs)h(that)0 5168 y(are)29 b(a)m(v)-5 b(ailable)28 b(from)g(the)g(CFITSIO)f(w)m(eb)i (site)f(are)h(also)f(v)m(ery)h(useful)e(for)h(learning)f(ho)m(w)h(to)h (use)f(CFITSIO.)f(T)-8 b(o)0 5281 y(learn)22 b(ev)m(en)h(more)g(ab)s (out)f(the)h(capabilities)d(of)j(the)g(CFITSIO)e(library)f(the)j(follo) m(wing)e(steps)h(are)h(recommended:)0 5441 y(1.)41 b(Read)31 b(the)f(follo)m(wing)f(short)h(`FITS)g(Primer')f(c)m(hapter)i(for)f(an) h(o)m(v)m(erview)g(of)f(the)h(structure)f(of)g(FITS)g(\014les.)0 5601 y(2.)40 b(Review)27 b(the)g(Programming)f(Guidelines)f(in)h (Chapter)g(4)i(to)g(b)s(ecome)f(familiar)e(with)h(the)i(con)m(v)m(en)m (tions)g(used)0 5714 y(b)m(y)i(the)h(CFITSIO)e(in)m(terface.)p eop %%Page: 10 18 10 17 bop 0 299 a Fj(10)1535 b Fh(CHAPTER)30 b(2.)112 b(CREA)-8 b(TING)30 b(THE)g(CFITSIO)f(LIBRAR)-8 b(Y)0 555 y Fj(3.)74 b(Refer)41 b(to)h(the)g(co)s(okb)s(o)s(ok.c,)j (listhead.c,)f(and)c(\014tscop)m(y)-8 b(.c)43 b(programs)e(that)h(are)g (included)c(with)i(this)h(re-)0 668 y(lease)g(for)f(examples)g(of)h (routines)e(that)i(p)s(erform)e(v)-5 b(arious)40 b(common)h(FITS)f (\014le)f(op)s(erations.)71 b(T)m(yp)s(e)40 b('mak)m(e)0 781 y(program)p 339 781 28 4 v 33 w(name')30 b(to)h(compile)f(and)f (link)g(these)i(programs)f(on)g(Unix)f(systems.)0 941 y(4.)40 b(W)-8 b(rite)29 b(a)f(simple)e(program)i(to)g(read)g(or)g (write)f(a)i(FITS)e(\014le)g(using)g(the)h(Basic)g(In)m(terface)h (routines)e(describ)s(ed)0 1054 y(in)i(Chapter)h(5.)0 1214 y(5.)79 b(Scan)43 b(through)f(the)h(more)g(sp)s(ecialized)f (routines)f(that)j(are)f(describ)s(ed)e(in)h(the)h(follo)m(wing)f(c)m (hapters)h(to)0 1327 y(b)s(ecome)31 b(familiar)d(with)h(the)i (functionalit)m(y)d(that)j(they)g(pro)m(vide.)0 1660 y Ff(2.5)135 b(Example)46 b(Program)0 1910 y Fj(The)c(follo)m(wing)g (listing)f(sho)m(ws)h(an)h(example)g(of)g(ho)m(w)g(to)g(use)g(the)g (CFITSIO)f(routines)f(in)h(a)h(C)g(program.)0 2023 y(Refer)26 b(to)g(the)g(co)s(okb)s(o)s(ok.c)g(program)f(that)i(is)d(included)f (with)h(the)i(CFITSIO)e(distribution)e(for)j(other)h(example)0 2136 y(routines.)0 2296 y(This)37 b(program)i(creates)h(a)f(new)f(FITS) g(\014le,)j(con)m(taining)d(a)h(FITS)f(image.)67 b(An)38 b(`EXPOSURE')h(k)m(eyw)m(ord)g(is)0 2409 y(written)26 b(to)h(the)f(header,)i(then)e(the)h(image)f(data)i(are)f(written)e(to)i (the)g(FITS)f(\014le)f(b)s(efore)i(closing)e(the)i(FITS)f(\014le.)0 2665 y Fe(#include)46 b("fitsio.h")92 b(/*)47 b(required)f(by)h(every)g (program)e(that)i(uses)g(CFITSIO)93 b(*/)0 2778 y(main\(\))0 2891 y({)191 3004 y(fitsfile)45 b(*fptr;)333 b(/*)47 b(pointer)f(to)h(the)g(FITS)g(file;)f(defined)g(in)h(fitsio.h)f(*/)191 3117 y(int)h(status,)f(ii,)h(jj;)191 3230 y(long)94 b(fpixel)46 b(=)i(1,)f(naxis)f(=)i(2,)f(nelements,)e(exposure;)191 3343 y(long)i(naxes[2])e(=)j({)f(300,)g(200)g(};)142 b(/*)47 b(image)g(is)g(300)g(pixels)f(wide)h(by)g(200)g(rows)f(*/)191 3456 y(short)g(array[200][300];)191 3681 y(status)g(=)h(0;)429 b(/*)48 b(initialize)d(status)h(before)g(calling)g(fitsio)g(routines)f (*/)191 3794 y(fits_create_file\(&fptr,)c("testfile.fits",)j (&status\);)140 b(/*)48 b(create)e(new)h(file)f(*/)191 4020 y(/*)h(Create)f(the)h(primary)f(array)g(image)h(\(16-bit)e(short)i (integer)f(pixels)g(*/)191 4133 y(fits_create_img\(fptr,)c(SHORT_IMG,)j (naxis,)h(naxes,)g(&status\);)191 4359 y(/*)h(Write)f(a)i(keyword;)d (must)i(pass)g(the)g(ADDRESS)e(of)j(the)f(value)f(*/)191 4472 y(exposure)f(=)j(1500.;)191 4585 y(fits_update_key\(fptr,)42 b(TLONG,)k("EXPOSURE",)f(&exposure,)430 4698 y("Total)h(Exposure)f (Time",)h(&status\);)191 4924 y(/*)h(Initialize)e(the)i(values)f(in)h (the)g(image)g(with)f(a)i(linear)e(ramp)g(function)g(*/)191 5036 y(for)h(\(jj)g(=)g(0;)g(jj)h(<)f(naxes[1];)e(jj++\))382 5149 y(for)i(\(ii)g(=)g(0;)g(ii)g(<)h(naxes[0];)d(ii++\))573 5262 y(array[jj][ii])f(=)j(ii)h(+)f(jj;)191 5488 y(nelements)e(=)j (naxes[0])d(*)j(naxes[1];)474 b(/*)48 b(number)e(of)h(pixels)f(to)h (write)g(*/)191 5714 y(/*)g(Write)f(the)h(array)g(of)g(integers)e(to)j (the)f(image)f(*/)p eop %%Page: 11 19 11 18 bop 0 299 a Fh(2.5.)72 b(EXAMPLE)31 b(PR)m(OGRAM)2618 b Fj(11)191 555 y Fe(fits_write_img\(fptr,)42 b(TSHORT,)k(fpixel,)g (nelements,)f(array[0],)g(&status\);)191 781 y(fits_close_file\(fptr,)d (&status\);)570 b(/*)47 b(close)g(the)g(file)f(*/)191 1007 y(fits_report_error\(stderr)o(,)c(status\);)93 b(/*)47 b(print)g(out)g(any)f(error)h(messages)e(*/)191 1120 y(return\()h(status)g(\);)0 1233 y(})p eop %%Page: 12 20 12 19 bop 0 299 a Fj(12)1535 b Fh(CHAPTER)30 b(2.)112 b(CREA)-8 b(TING)30 b(THE)g(CFITSIO)f(LIBRAR)-8 b(Y)p eop %%Page: 13 21 13 20 bop 0 1225 a Fg(Chapter)65 b(3)0 1687 y Fm(A)78 b(FITS)f(Primer)0 2180 y Fj(This)22 b(section)j(giv)m(es)f(a)h(brief)d (o)m(v)m(erview)j(of)f(the)h(structure)e(of)i(FITS)e(\014les.)37 b(Users)24 b(should)f(refer)g(to)i(the)g(do)s(cumen-)0 2293 y(tation)i(a)m(v)-5 b(ailable)27 b(from)g(the)g(NOST,)f(as)i (describ)s(ed)d(in)h(the)h(in)m(tro)s(duction,)f(for)h(more)g(detailed) g(information)e(on)0 2406 y(FITS)30 b(formats.)0 2566 y(FITS)e(w)m(as)h(\014rst)g(dev)m(elop)s(ed)f(in)f(the)i(late)h(1970's) h(as)e(a)g(standard)f(data)i(in)m(terc)m(hange)f(format)g(b)s(et)m(w)m (een)h(v)-5 b(arious)0 2679 y(astronomical)34 b(observ)-5 b(atories.)51 b(Since)33 b(then)h(FITS)f(has)h(b)s(ecome)g(the)h (standard)e(data)i(format)f(supp)s(orted)e(b)m(y)0 2791 y(most)f(astronomical)f(data)h(analysis)e(soft)m(w)m(are)j(pac)m(k)-5 b(ages.)0 2952 y(A)34 b(FITS)f(\014le)f(consists)h(of)h(one)g(or)g (more)g(Header)g(+)f(Data)i(Units)e(\(HDUs\),)j(where)d(the)h(\014rst)f (HDU)h(is)f(called)0 3065 y(the)k(`Primary)e(HDU',)j(or)f(`Primary)e (Arra)m(y'.)60 b(The)36 b(primary)f(arra)m(y)i(con)m(tains)g(an)f (N-dimensional)f(arra)m(y)i(of)0 3177 y(pixels,)26 b(suc)m(h)h(as)h(a)f (1-D)h(sp)s(ectrum,)f(a)h(2-D)g(image,)h(or)e(a)g(3-D)i(data)f(cub)s (e.)39 b(Fiv)m(e)27 b(di\013eren)m(t)g(primary)e(data)j(t)m(yp)s(es)0 3290 y(are)e(supp)s(orted:)37 b(Unsigned)24 b(8-bit)i(b)m(ytes,)h(16)g (and)e(32-bit)h(signed)e(in)m(tegers,)j(and)f(32)g(and)f(64-bit)h (\015oating)g(p)s(oin)m(t)0 3403 y(reals.)40 b(FITS)29 b(also)h(has)g(a)g(con)m(v)m(en)m(tion)i(for)d(storing)h(16)h(and)e (32-bit)h(unsigned)e(in)m(tegers)j(\(see)g(the)f(later)g(section)0 3516 y(en)m(titled)d(`Unsigned)g(In)m(tegers')i(for)e(more)h (details\).)39 b(The)27 b(primary)f(HDU)j(ma)m(y)f(also)g(consist)f(of) h(only)f(a)h(header)0 3629 y(with)h(a)i(n)m(ull)d(arra)m(y)j(con)m (taining)f(no)g(data)h(pixels.)0 3789 y(An)m(y)i(n)m(um)m(b)s(er)e(of)h (additional)f(HDUs)i(ma)m(y)g(follo)m(w)f(the)g(primary)f(arra)m(y;)j (these)f(additional)e(HDUs)i(are)g(called)0 3902 y(FITS)d (`extensions'.)40 b(There)30 b(are)h(curren)m(tly)e(3)i(t)m(yp)s(es)g (of)f(extensions)g(de\014ned)f(b)m(y)h(the)h(FITS)f(standard:)136 4171 y Fc(\017)46 b Fj(Image)31 b(Extension)f(-)h(a)f(N-dimensional)e (arra)m(y)j(of)g(pixels,)e(lik)m(e)g(in)g(a)i(primary)d(arra)m(y)136 4368 y Fc(\017)46 b Fj(ASCI)s(I)29 b(T)-8 b(able)30 b(Extension)g(-)g (ro)m(ws)h(and)e(columns)g(of)i(data)g(in)e(ASCI)s(I)g(c)m(haracter)j (format)136 4564 y Fc(\017)46 b Fj(Binary)30 b(T)-8 b(able)30 b(Extension)f(-)i(ro)m(ws)f(and)g(columns)f(of)i(data)g(in)e(binary)f (represen)m(tation)0 4833 y(In)33 b(eac)m(h)i(case)g(the)f(HDU)h (consists)f(of)g(an)g(ASCI)s(I)e(Header)i(Unit)g(follo)m(w)m(ed)f(b)m (y)h(an)g(optional)f(Data)i(Unit.)51 b(F)-8 b(or)0 4946 y(historical)34 b(reasons,)j(eac)m(h)f(Header)g(or)g(Data)h(unit)d(m)m (ust)h(b)s(e)g(an)g(exact)i(m)m(ultiple)c(of)j(2880)h(8-bit)e(b)m(ytes) h(long.)0 5059 y(An)m(y)30 b(un)m(used)g(space)g(is)g(padded)f(with)g (\014ll)f(c)m(haracters)k(\(ASCI)s(I)d(blanks)g(or)i(zeros\).)0 5219 y(Eac)m(h)i(Header)f(Unit)g(consists)g(of)g(an)m(y)g(n)m(um)m(b)s (er)f(of)i(80-c)m(haracter)i(k)m(eyw)m(ord)d(records)g(or)g(`card)h (images')f(whic)m(h)0 5332 y(ha)m(v)m(e)g(the)e(general)h(form:)95 5601 y Fe(KEYNAME)46 b(=)i(value)e(/)i(comment)d(string)95 5714 y(NULLKEY)h(=)334 b(/)48 b(comment:)d(This)i(keyword)f(has)g(no)i (value)1905 5942 y Fj(13)p eop %%Page: 14 22 14 21 bop 0 299 a Fj(14)2398 b Fh(CHAPTER)30 b(3.)112 b(A)30 b(FITS)g(PRIMER)0 555 y Fj(The)35 b(k)m(eyw)m(ord)i(names)f(ma)m (y)g(b)s(e)g(up)f(to)h(8)h(c)m(haracters)g(long)f(and)f(can)h(only)g (con)m(tain)g(upp)s(ercase)f(letters,)j(the)0 668 y(digits)23 b(0-9,)k(the)e(h)m(yphen,)g(and)f(the)h(underscore)e(c)m(haracter.)41 b(The)24 b(k)m(eyw)m(ord)h(name)g(is)e(\(usually\))g(follo)m(w)m(ed)i (b)m(y)f(an)0 781 y(equals)k(sign)g(and)g(a)g(space)i(c)m(haracter)g (\(=)e(\))h(in)e(columns)h(9)h(-)f(10)i(of)f(the)f(record,)h(follo)m(w) m(ed)g(b)m(y)f(the)h(v)-5 b(alue)28 b(of)h(the)0 894 y(k)m(eyw)m(ord)34 b(whic)m(h)f(ma)m(y)h(b)s(e)f(either)g(an)h(in)m (teger,)h(a)f(\015oating)f(p)s(oin)m(t)g(n)m(um)m(b)s(er,)h(a)g(c)m (haracter)h(string)d(\(enclosed)i(in)0 1007 y(single)26 b(quotes\),)k(or)e(a)g(b)s(o)s(olean)f(v)-5 b(alue)27 b(\(the)h(letter)g(T)g(or)f(F\).)i(A)f(k)m(eyw)m(ord)g(ma)m(y)h(also)e (ha)m(v)m(e)i(a)g(n)m(ull)c(or)j(unde\014ned)0 1120 y(v)-5 b(alue)30 b(if)f(there)i(is)e(no)h(sp)s(eci\014ed)f(v)-5 b(alue)30 b(string,)g(as)g(in)f(the)i(second)f(example,)h(ab)s(o)m(v)m (e)0 1280 y(The)42 b(last)g(k)m(eyw)m(ord)h(in)e(the)i(header)f(is)f (alw)m(a)m(ys)i(the)g(`END')g(k)m(eyw)m(ord)g(whic)m(h)e(has)h(no)h(v) -5 b(alue)41 b(or)i(commen)m(t)0 1393 y(\014elds.)c(There)30 b(are)h(man)m(y)f(rules)f(go)m(v)m(erning)i(the)f(exact)i(format)f(of)f (a)h(k)m(eyw)m(ord)f(record)h(\(see)g(the)f(NOST)g(FITS)0 1506 y(Standard\))c(so)i(it)e(is)h(b)s(etter)g(to)h(rely)e(on)h (standard)g(in)m(terface)g(soft)m(w)m(are)i(lik)m(e)d(CFITSIO)g(to)i (correctly)g(construct)0 1619 y(or)i(to)h(parse)g(the)f(k)m(eyw)m(ord)h (records)f(rather)g(than)h(try)f(to)h(deal)f(directly)f(with)g(the)h (ra)m(w)h(FITS)f(formats.)0 1779 y(Eac)m(h)37 b(Header)g(Unit)e(b)s (egins)g(with)g(a)h(series)g(of)g(required)f(k)m(eyw)m(ords)h(whic)m(h) f(dep)s(end)g(on)h(the)g(t)m(yp)s(e)h(of)f(HDU.)0 1892 y(These)31 b(required)f(k)m(eyw)m(ords)i(sp)s(ecify)f(the)g(size)h(and) f(format)h(of)g(the)g(follo)m(wing)e(Data)j(Unit.)44 b(The)31 b(header)g(ma)m(y)0 2005 y(con)m(tain)g(other)g(optional)e(k)m (eyw)m(ords)i(to)h(describ)s(e)d(other)h(asp)s(ects)h(of)g(the)g(data,) g(suc)m(h)g(as)g(the)f(units)f(or)i(scaling)0 2118 y(v)-5 b(alues.)43 b(Other)31 b(COMMENT)g(or)g(HISTOR)-8 b(Y)30 b(k)m(eyw)m(ords)i(are)g(also)f(frequen)m(tly)g(added)f(to)i(further)e (do)s(cumen)m(t)0 2230 y(the)h(data)g(\014le.)0 2391 y(The)36 b(optional)f(Data)j(Unit)e(immediately)e(follo)m(ws)i(the)g (last)g(2880-b)m(yte)j(blo)s(c)m(k)d(in)f(the)h(Header)h(Unit.)58 b(Some)0 2503 y(HDUs)31 b(do)f(not)h(ha)m(v)m(e)g(a)g(Data)h(Unit)e (and)g(only)f(consist)h(of)h(the)f(Header)h(Unit.)0 2664 y(If)24 b(there)i(is)e(more)h(than)f(one)h(HDU)h(in)e(the)h(FITS)f (\014le,)h(then)g(the)g(Header)h(Unit)e(of)h(the)g(next)g(HDU)h (immediately)0 2777 y(follo)m(ws)e(the)g(last)h(2880-b)m(yte)i(blo)s(c) m(k)d(of)h(the)f(previous)f(Data)k(Unit)c(\(or)i(Header)g(Unit)f(if)f (there)i(is)f(no)g(Data)i(Unit\).)0 2937 y(The)k(main)f(required)g(k)m (eyw)m(ords)h(in)f(FITS)h(primary)f(arra)m(ys)h(or)h(image)f (extensions)g(are:)136 3172 y Fc(\017)46 b Fj(BITPIX)39 b({)h(de\014nes)f(the)g(data)h(t)m(yp)s(e)g(of)f(the)h(arra)m(y:)59 b(8,)42 b(16,)h(32,)g(-32,)g(-64)d(for)f(unsigned)f(8{bit)h(b)m(yte,) 227 3284 y(16{bit)h(signed)f(in)m(teger,)j(32{bit)f(signed)d(in)m (teger,)43 b(32{bit)d(IEEE)f(\015oating)g(p)s(oin)m(t,)i(and)f(64{bit)g (IEEE)227 3397 y(double)29 b(precision)g(\015oating)h(p)s(oin)m(t,)g (resp)s(ectiv)m(ely)-8 b(.)136 3585 y Fc(\017)46 b Fj(NAXIS)30 b({)h(the)g(n)m(um)m(b)s(er)e(of)h(dimensions)e(in)h(the)i(arra)m(y)-8 b(,)31 b(usually)d(0,)j(1,)g(2,)g(3,)g(or)g(4.)136 3773 y Fc(\017)46 b Fj(NAXISn)30 b({)h(\(n)f(ranges)g(from)g(1)h(to)g (NAXIS\))g(de\014nes)e(the)i(size)f(of)h(eac)m(h)g(dimension.)0 4008 y(FITS)e(tables)h(start)h(with)e(the)h(k)m(eyw)m(ord)g(XTENSION)g (=)f(`T)-8 b(ABLE')31 b(\(for)f(ASCI)s(I)f(tables\))h(or)g(XTENSION)f (=)0 4120 y(`BINT)-8 b(ABLE')32 b(\(for)e(binary)f(tables\))h(and)g(ha) m(v)m(e)i(the)e(follo)m(wing)f(main)g(k)m(eyw)m(ords:)136 4355 y Fc(\017)46 b Fj(TFIELDS)30 b({)h(n)m(um)m(b)s(er)e(of)h (\014elds)f(or)i(columns)e(in)g(the)h(table)136 4543 y Fc(\017)46 b Fj(NAXIS2)31 b({)g(n)m(um)m(b)s(er)e(of)h(ro)m(ws)h(in)e (the)h(table)136 4731 y Fc(\017)46 b Fj(TTYPEn)29 b({)i(for)f(eac)m(h)i (column)d(\(n)h(ranges)h(from)f(1)g(to)h(TFIELDS\))g(giv)m(es)f(the)h (name)f(of)h(the)f(column)136 4918 y Fc(\017)46 b Fj(TF)m(ORMn)31 b({)f(the)h(data)g(t)m(yp)s(e)f(of)h(the)g(column)136 5106 y Fc(\017)46 b Fj(TUNITn)30 b({)g(the)h(ph)m(ysical)e(units)g(of)h (the)h(column)e(\(optional\))0 5341 y(Users)e(should)e(refer)i(to)g (the)h(FITS)e(Supp)s(ort)f(O\016ce)i(at)h Fe(http://fits.gsfc.nasa.go)o (v)21 b Fj(for)27 b(futher)f(informa-)0 5454 y(tion)k(ab)s(out)g(the)h (FITS)e(format)i(and)f(related)g(soft)m(w)m(are)i(pac)m(k)-5 b(ages.)p eop %%Page: 15 23 15 22 bop 0 1225 a Fg(Chapter)65 b(4)0 1687 y Fm(Programming)77 b(Guidelines)0 2216 y Ff(4.1)135 b(CFITSIO)44 b(De\014nitions)0 2466 y Fj(An)m(y)30 b(program)g(that)h(uses)f(the)h(CFITSIO)d(in)m (terface)j(m)m(ust)f(include)e(the)j(\014tsio.h)e(header)h(\014le)g (with)f(the)h(state-)0 2579 y(men)m(t)95 2818 y Fe(#include)46 b("fitsio.h")0 3057 y Fj(This)29 b(header)i(\014le)g(con)m(tains)g(the) g(protot)m(yp)s(es)h(for)f(all)f(the)h(CFITSIO)f(user)g(in)m(terface)i (routines)e(as)h(w)m(ell)f(as)i(the)0 3170 y(de\014nitions)e(of)i(v)-5 b(arious)31 b(constan)m(ts)i(used)e(in)g(the)i(in)m(terface.)46 b(It)32 b(also)g(de\014nes)f(a)i(C)f(structure)f(of)h(t)m(yp)s(e)h (`\014ts\014le')0 3283 y(that)j(is)f(used)g(b)m(y)g(CFITSIO)f(to)j (store)f(the)g(relev)-5 b(an)m(t)36 b(parameters)g(that)g(de\014ne)f (the)h(format)g(of)g(a)g(particular)0 3396 y(FITS)c(\014le.)47 b(Application)31 b(programs)i(m)m(ust)g(de\014ne)f(a)h(p)s(oin)m(ter)f (to)h(this)f(structure)h(for)f(eac)m(h)i(FITS)e(\014le)g(that)i(is)0 3508 y(to)i(b)s(e)f(op)s(ened.)56 b(This)34 b(structure)h(is)g (initialized)d(\(i.e.,)38 b(memory)d(is)g(allo)s(cated)g(for)h(the)g (structure\))f(when)g(the)0 3621 y(FITS)h(\014le)f(is)h(\014rst)f(op)s (ened)h(or)g(created)i(with)d(the)h(\014ts)p 1949 3621 28 4 v 33 w(op)s(en)p 2172 3621 V 32 w(\014le)f(or)i(\014ts)p 2596 3621 V 32 w(create)p 2864 3621 V 34 w(\014le)f(routines.)58 b(This)34 b(\014ts\014le)0 3734 y(p)s(oin)m(ter)c(is)h(then)g(passed)g (as)g(the)h(\014rst)e(argumen)m(t)i(to)g(ev)m(ery)g(other)g(CFITSIO)d (routine)i(that)h(op)s(erates)g(on)f(the)0 3847 y(FITS)h(\014le.)47 b(Application)31 b(programs)i(m)m(ust)g(not)g(directly)e(read)i(or)g (write)f(elemen)m(ts)h(in)f(this)g(\014ts\014le)f(structure)0 3960 y(b)s(ecause)f(the)h(de\014nition)d(of)j(the)f(structure)g(ma)m(y) h(c)m(hange)g(in)f(future)f(v)m(ersions)h(of)g(CFITSIO.)0 4120 y(A)45 b(n)m(um)m(b)s(er)e(of)i(sym)m(b)s(olic)e(constan)m(ts)j (are)f(also)f(de\014ned)g(in)f(\014tsio.h)h(for)g(the)h(con)m(v)m (enience)h(of)f(application)0 4233 y(programmers.)55 b(Use)35 b(of)h(these)f(sym)m(b)s(olic)f(constan)m(ts)i(rather)f(than)g (the)h(actual)f(n)m(umeric)f(v)-5 b(alue)35 b(will)d(help)i(to)0 4346 y(mak)m(e)d(the)g(source)f(co)s(de)h(more)g(readable)e(and)h (easier)h(for)f(others)g(to)h(understand.)0 4585 y Fe(String)46 b(Lengths,)g(for)h(use)f(when)h(allocating)e(character)g(arrays:)95 4811 y(#define)h(FLEN_FILENAME)e(1025)j(/*)g(max)g(length)f(of)h(a)h (filename)857 b(*/)95 4924 y(#define)46 b(FLEN_KEYWORD)140 b(72)95 b(/*)47 b(max)g(length)f(of)h(a)h(keyword)905 b(*/)95 5036 y(#define)46 b(FLEN_CARD)284 b(81)95 b(/*)47 b(max)g(length)f(of)h(a)h(FITS)f(header)f(card)476 b(*/)95 5149 y(#define)46 b(FLEN_VALUE)236 b(71)95 b(/*)47 b(max)g(length)f(of) h(a)h(keyword)e(value)g(string)285 b(*/)95 5262 y(#define)46 b(FLEN_COMMENT)140 b(73)95 b(/*)47 b(max)g(length)f(of)h(a)h(keyword)e (comment)g(string)189 b(*/)95 5375 y(#define)46 b(FLEN_ERRMSG)188 b(81)95 b(/*)47 b(max)g(length)f(of)h(a)h(CFITSIO)e(error)g(message)237 b(*/)95 5488 y(#define)46 b(FLEN_STATUS)188 b(31)95 b(/*)47 b(max)g(length)f(of)h(a)h(CFITSIO)e(status)g(text)g(string)h(*/)95 5714 y(Note)g(that)g(FLEN_KEYWORD)d(is)j(longer)f(than)h(the)g(nominal) f(8-character)f(keyword)1905 5942 y Fj(15)p eop %%Page: 16 24 16 23 bop 0 299 a Fj(16)1763 b Fh(CHAPTER)29 b(4.)112 b(PR)m(OGRAMMING)32 b(GUIDELINES)95 555 y Fe(name)47 b(length)f(because)g(the)h(HIERARCH)e(convention)g(supports)h(longer)g (keyword)g(names.)0 781 y(Access)g(modes)g(when)h(opening)f(a)h(FITS)g (file:)95 1007 y(#define)f(READONLY)94 b(0)95 1120 y(#define)46 b(READWRITE)g(1)0 1346 y(BITPIX)g(data)h(type)f(code)h(values)f(for)h (FITS)g(images:)95 1571 y(#define)f(BYTE_IMG)284 b(8)96 b(/*)f(8-bit)46 b(unsigned)f(integers)h(*/)95 1684 y(#define)g (SHORT_IMG)189 b(16)95 b(/*)47 b(16-bit)141 b(signed)46 b(integers)g(*/)95 1797 y(#define)g(LONG_IMG)237 b(32)95 b(/*)47 b(32-bit)141 b(signed)46 b(integers)g(*/)95 1910 y(#define)g(FLOAT_IMG)141 b(-32)95 b(/*)47 b(32-bit)f(single)g (precision)f(floating)h(point)g(*/)95 2023 y(#define)g(DOUBLE_IMG)93 b(-64)i(/*)47 b(64-bit)f(double)g(precision)f(floating)h(point)g(*/)95 2249 y(The)h(following)f(4)h(data)g(type)f(codes)h(are)g(also)f (supported)g(by)h(CFITSIO:)95 2362 y(#define)f(LONGLONG_IMG)f(64)i(/*)g (64-bit)f(long)h(signed)f(integers)f(*/)95 2475 y(#define)h(SBYTE_IMG) 93 b(10)143 b(/*)95 b(8-bit)46 b(signed)g(integers,)g(equivalent)f(to)i (*/)1241 2588 y(/*)95 b(BITPIX)46 b(=)h(8,)h(BSCALE)e(=)h(1,)g(BZERO)g (=)g(-128)g(*/)95 2700 y(#define)f(USHORT_IMG)93 b(20)i(/*)47 b(16-bit)f(unsigned)g(integers,)f(equivalent)g(to)i(*/)1241 2813 y(/*)95 b(BITPIX)46 b(=)h(16,)g(BSCALE)f(=)i(1,)f(BZERO)f(=)i (32768)e(*/)95 2926 y(#define)g(ULONG_IMG)141 b(40)95 b(/*)47 b(32-bit)f(unsigned)g(integers,)f(equivalent)g(to)i(*/)1241 3039 y(/*)95 b(BITPIX)46 b(=)h(32,)g(BSCALE)f(=)i(1,)f(BZERO)f(=)i (2147483648)d(*/)0 3265 y(Codes)h(for)h(the)g(data)g(type)f(of)i (binary)e(table)g(columns)g(and/or)g(for)h(the)0 3378 y(data)g(type)f(of)h(variables)f(when)g(reading)g(or)h(writing)f (keywords)g(or)h(data:)1432 3604 y(DATATYPE)714 b(TFORM)46 b(CODE)95 3717 y(#define)g(TBIT)476 b(1)96 b(/*)1335 b('X')47 b(*/)95 3830 y(#define)f(TBYTE)381 b(11)95 b(/*)47 b(8-bit)f(unsigned)g(byte,)332 b('B')47 b(*/)95 3942 y(#define)f(TLOGICAL)237 b(14)95 b(/*)47 b(logicals)e(\(int)i(for)g (keywords)236 b(*/)1289 4055 y(/*)95 b(and)46 b(char)h(for)g(table)f (cols)142 b('L')47 b(*/)95 4168 y(#define)f(TSTRING)285 b(16)95 b(/*)47 b(ASCII)f(string,)666 b('A')47 b(*/)95 4281 y(#define)f(TSHORT)333 b(21)95 b(/*)47 b(signed)f(short,)666 b('I')47 b(*/)95 4394 y(#define)f(TINT32BIT)189 b(41)95 b(/*)47 b(signed)f(32-bit)g(int,)428 b('J')47 b(*/)95 4507 y(#define)f(TLONG)381 b(41)95 b(/*)47 b(signed)f(long,)905 b(*/)95 4620 y(#define)46 b(TFLOAT)333 b(42)95 b(/*)47 b(single)f(precision)f(float,)189 b('E')47 b(*/)95 4733 y(#define)f(TDOUBLE)285 b(82)95 b(/*)47 b(double)f(precision)f(float,) 189 b('D')47 b(*/)95 4846 y(#define)f(TCOMPLEX)237 b(83)95 b(/*)47 b(complex)f(\(pair)g(of)h(floats\))141 b('C')47 b(*/)95 4959 y(#define)f(TDBLCOMPLEX)f(163)95 b(/*)47 b(double)f(complex)g(\(2)h(doubles\))e('M')i(*/)95 5185 y(The)g(following)f(data)g(type)h(codes)f(are)h(also)g(supported)e(by)i (CFITSIO:)95 5297 y(#define)f(TINT)429 b(31)95 b(/*)47 b(int)1335 b(*/)95 5410 y(#define)46 b(TSBYTE)333 b(12)95 b(/*)47 b(8-bit)f(signed)g(byte,)428 b('S')47 b(*/)95 5523 y(#define)f(TUINT)381 b(30)95 b(/*)47 b(unsigned)e(int)715 b('V')47 b(*/)95 5636 y(#define)f(TUSHORT)285 b(20)95 b(/*)47 b(unsigned)e(short)619 b('U')95 b(*/)p eop %%Page: 17 25 17 24 bop 0 299 a Fh(4.2.)72 b(CURRENT)30 b(HEADER)h(D)m(A)-8 b(T)g(A)32 b(UNIT)e(\(CHDU\))1786 b Fj(17)95 555 y Fe(#define)46 b(TULONG)333 b(40)95 b(/*)47 b(unsigned)e(long)858 b(*/)95 668 y(#define)46 b(TLONGLONG)189 b(81)95 b(/*)47 b(64-bit)f(long)h (signed)f(integer)f('K')i(*/)0 894 y(HDU)g(type)g(code)f(values)g (\(value)g(returned)g(when)h(moving)f(to)h(new)g(HDU\):)95 1120 y(#define)f(IMAGE_HDU)93 b(0)i(/*)48 b(Primary)d(Array)i(or)g (IMAGE)f(HDU)h(*/)95 1233 y(#define)f(ASCII_TBL)93 b(1)i(/*)48 b(ASCII)94 b(table)46 b(HDU)h(*/)95 1346 y(#define)f(BINARY_TBL)f(2)95 b(/*)48 b(Binary)e(table)g(HDU)h(*/)95 1458 y(#define)f(ANY_HDU)142 b(-1)94 b(/*)48 b(matches)d(any)i(type)g(of)g(HDU)g(*/)0 1684 y(Column)f(name)h(and)g(string)f(matching)f(case-sensitivity:)95 1910 y(#define)h(CASESEN)142 b(1)g(/*)48 b(do)f(case-sensitive)d (string)i(match)g(*/)95 2023 y(#define)g(CASEINSEN)g(0)142 b(/*)48 b(do)f(case-insensitive)c(string)j(match)h(*/)0 2249 y(Logical)f(states)g(\(if)h(TRUE)f(and)h(FALSE)g(are)g(not)g (already)e(defined\):)95 2475 y(#define)h(TRUE)h(1)95 2588 y(#define)f(FALSE)h(0)0 2813 y(Values)f(to)h(represent)f (undefined)f(floating)g(point)i(numbers:)95 3039 y(#define)f (FLOATNULLVALUE)e(-9.11912E-36F)95 3152 y(#define)i(DOUBLENULLVALUE)e (-9.1191291391491E-36)0 3378 y(Image)i(compression)f(algorithm)g (definitions)95 3604 y(#define)h(RICE_1)285 b(11)95 3717 y(#define)46 b(GZIP_1)285 b(21)95 3830 y(#define)46 b(PLIO_1)285 b(31)0 4306 y Ff(4.2)135 b(Curren)l(t)46 b(Header)f(Data)h(Unit)g (\(CHDU\))0 4585 y Fj(The)37 b(concept)h(of)g(the)f(Curren)m(t)g (Header)g(and)g(Data)i(Unit,)g(or)e(CHDU,)h(is)e(fundamen)m(tal)h(to)h (the)f(use)g(of)h(the)0 4698 y(CFITSIO)31 b(library)-8 b(.)44 b(A)32 b(simple)f(FITS)g(image)i(ma)m(y)g(only)e(con)m(tain)i(a) f(single)f(Header)i(and)f(Data)h(unit)e(\(HDU\),)0 4811 y(but)39 b(in)f(general)i(FITS)f(\014les)g(can)h(con)m(tain)g(m)m (ultiple)e(Header)i(Data)h(Units)e(\(also)h(kno)m(wn)f(as)h (`extensions'\),)0 4924 y(concatenated)c(one)f(after)f(the)h(other)f (in)f(the)h(\014le.)52 b(The)33 b(user)h(can)g(sp)s(ecify)f(whic)m(h)g (HDU)i(should)d(b)s(e)h(initially)0 5036 y(op)s(ened)j(at)i(run)d(time) i(b)m(y)g(giving)f(the)h(HDU)h(name)f(or)g(n)m(um)m(b)s(er)f(after)h (the)g(ro)s(ot)h(\014le)e(name.)60 b(F)-8 b(or)38 b(example,)0 5149 y('m)m(y\014le.\014ts[4]')h(op)s(ens)e(the)h(5th)h(HDU)g(in)e(the) h(\014le)f(\(note)i(that)g(the)f(n)m(um)m(b)s(ering)e(starts)j(with)e (0\),)k(and)c('m)m(y-)0 5262 y(\014le.\014ts[EVENTS])j(op)s(ens)g(the)h (HDU)h(with)d(the)i(name)g('EVENTS')g(\(as)g(de\014ned)f(b)m(y)h(the)g (EXTNAME)g(or)0 5375 y(HDUNAME)35 b(k)m(eyw)m(ords\).)50 b(If)33 b(no)g(HDU)h(is)e(sp)s(eci\014ed)g(then)h(CFITSIO)e(op)s(ens)i (the)g(\014rst)g(HDU)h(\(the)g(primary)0 5488 y(arra)m(y\))24 b(b)m(y)e(default.)38 b(The)22 b(CFITSIO)f(routines)h(whic)m(h)g(read)g (and)g(write)h(data)g(only)f(op)s(erate)h(within)e(the)i(op)s(ened)0 5601 y(HDU,)32 b(Other)e(CFITSIO)f(routines)h(are)h(pro)m(vided)e(to)j (mo)m(v)m(e)g(to)f(and)f(op)s(en)g(an)m(y)h(other)g(existing)f(HDU)h (within)0 5714 y(the)g(FITS)e(\014le)h(or)g(to)h(app)s(end)e(or)h (insert)f(new)h(HDUs)h(in)e(the)i(FITS)f(\014le.)p eop %%Page: 18 26 18 25 bop 0 299 a Fj(18)1763 b Fh(CHAPTER)29 b(4.)112 b(PR)m(OGRAMMING)32 b(GUIDELINES)0 555 y Ff(4.3)135 b(F)-11 b(unction)44 b(Names)i(and)f(V)-11 b(ariable)46 b(Datat)l(yp)t(es)0 806 y Fj(Most)33 b(of)f(the)g(CFITSIO)f(routines)g(ha)m(v)m(e)i(b)s (oth)e(a)i(short)e(name)h(as)h(w)m(ell)e(as)h(a)g(longer)g(descriptiv)m (e)f(name.)45 b(The)0 919 y(short)32 b(name)g(is)f(only)g(5)i(or)f(6)g (c)m(haracters)h(long)f(and)g(is)f(similar)e(to)k(the)f(subroutine)e (name)i(in)f(the)h(F)-8 b(ortran-77)0 1032 y(v)m(ersion)37 b(of)h(FITSIO.)f(The)h(longer)f(name)h(is)f(more)h(descriptiv)m(e)f (and)g(it)g(is)g(recommended)h(that)g(it)g(b)s(e)f(used)0 1145 y(instead)30 b(of)g(the)h(short)f(name)g(to)h(more)g(clearly)f(do) s(cumen)m(t)g(the)g(source)h(co)s(de.)0 1305 y(Man)m(y)c(of)f(the)g (CFITSIO)f(routines)g(come)i(in)d(families)g(whic)m(h)h(di\013er)g (only)g(in)g(the)h(data)h(t)m(yp)s(e)f(of)g(the)g(asso)s(ciated)0 1418 y(parameter\(s\).)45 b(The)31 b(data)h(t)m(yp)s(e)g(of)g(these)g (routines)e(is)h(indicated)f(b)m(y)h(the)h(su\016x)e(of)i(the)g (routine)e(name.)44 b(The)0 1530 y(short)27 b(routine)g(names)h(ha)m(v) m(e)h(a)f(1)g(or)f(2)h(c)m(haracter)i(su\016x)c(\(e.g.,)31 b('j')c(in)g('\013pkyj'\))h(while)d(the)j(long)f(routine)g(names)0 1643 y(ha)m(v)m(e)32 b(a)e(4)h(c)m(haracter)h(or)e(longer)g(su\016x)g (as)g(sho)m(wn)g(in)f(the)i(follo)m(wing)e(table:)191 1905 y Fe(Long)285 b(Short)94 b(Data)191 2018 y(Names)237 b(Names)94 b(Type)191 2131 y(-----)237 b(-----)94 b(----)191 2244 y(_bit)381 b(x)190 b(bit)191 2357 y(_byt)381 b(b)190 b(unsigned)46 b(byte)191 2469 y(_sbyt)333 b(sb)142 b(signed)46 b(byte)191 2582 y(_sht)381 b(i)190 b(short)47 b(integer)191 2695 y(_lng)381 b(j)190 b(long)47 b(integer)191 2808 y(_lnglng)237 b(jj)142 b(8-byte)46 b(LONGLONG)g(integer)g(\(see)g(note) h(below\))191 2921 y(_usht)333 b(ui)142 b(unsigned)46 b(short)g(integer)191 3034 y(_ulng)333 b(uj)142 b(unsigned)46 b(long)g(integer)191 3147 y(_uint)333 b(uk)142 b(unsigned)46 b(int)h(integer)191 3260 y(_int)381 b(k)190 b(int)47 b(integer)191 3373 y(_flt)381 b(e)190 b(real)47 b(exponential)e (floating)g(point)i(\(float\))191 3486 y(_fixflt)237 b(f)190 b(real)47 b(fixed-decimal)d(format)i(floating)g(point)g (\(float\))191 3599 y(_dbl)381 b(d)190 b(double)46 b(precision)g(real)g (floating-point)e(\(double\))191 3711 y(_fixdbl)237 b(g)190 b(double)46 b(precision)g(fixed-format)e(floating)i(point)g(\(double\)) 191 3824 y(_cmp)381 b(c)190 b(complex)46 b(reals)g(\(pairs)h(of)g (float)f(values\))191 3937 y(_fixcmp)237 b(fc)142 b(complex)46 b(reals,)g(fixed-format)f(floating)g(point)191 4050 y(_dblcmp)237 b(m)190 b(double)46 b(precision)g(complex)f(\(pairs)i(of)g(double)f (values\))191 4163 y(_fixdblcmp)93 b(fm)142 b(double)46 b(precision)g(complex,)f(fixed-format)g(floating)g(point)191 4276 y(_log)381 b(l)190 b(logical)46 b(\(int\))191 4389 y(_str)381 b(s)190 b(character)46 b(string)0 4650 y Fj(The)32 b(logical)g(data)i(t)m(yp)s(e)f(corresp)s(onds)e(to)j(`in)m(t')e(for)h (logical)f(k)m(eyw)m(ord)h(v)-5 b(alues,)33 b(and)f(`b)m(yte')i(for)f (logical)f(binary)0 4763 y(table)39 b(columns.)66 b(In)39 b(other)g(w)m(ords,)i(the)f(v)-5 b(alue)38 b(when)h(writing)e(a)j (logical)e(k)m(eyw)m(ord)i(m)m(ust)f(b)s(e)g(stored)g(in)f(an)0 4876 y(`in)m(t')g(v)-5 b(ariable,)38 b(and)g(m)m(ust)f(b)s(e)g(stored)h (in)f(a)h(`c)m(har')h(arra)m(y)f(when)f(reading)g(or)g(writing)f(to)j (`L')f(columns)e(in)h(a)0 4989 y(binary)e(table.)59 b(Inplicit)34 b(data)j(t)m(yp)s(e)f(con)m(v)m(ersion)h(is)f(not)h(supp)s(orted)d(for) i(logical)g(table)h(columns,)g(but)f(is)f(for)0 5102 y(k)m(eyw)m(ords,)30 b(so)f(a)h(logical)e(k)m(eyw)m(ord)i(ma)m(y)f(b)s (e)g(read)f(and)h(cast)h(to)g(an)m(y)f(n)m(umerical)f(data)h(t)m(yp)s (e;)h(a)g(returned)d(v)-5 b(alue)0 5215 y(=)30 b(0)h(indicates)e (false,)h(and)g(an)m(y)h(other)f(v)-5 b(alue)30 b(=)g(true.)0 5375 y(The)37 b(`in)m(t')h(data)g(t)m(yp)s(e)g(ma)m(y)g(b)s(e)f(2)h(b)m (ytes)h(long)e(on)g(some)h(IBM)h(PC)e(compatible)g(systems)g(and)g(is)g (usually)f(4)0 5488 y(b)m(ytes)27 b(long)f(on)h(most)g(other)g (systems.)39 b(Some)27 b(64-bit)g(mac)m(hines,)g(ho)m(w)m(ev)m(er,)i (lik)m(e)d(the)h(Dec)h(Alpha/OSF,)e(de\014ne)0 5601 y(the)j(`short',)h (`in)m(t',)g(and)e(`long')h(in)m(teger)h(data)g(t)m(yp)s(es)f(to)h(b)s (e)e(2,)i(4,)g(and)f(8)g(b)m(ytes)h(long,)f(resp)s(ectiv)m(ely)-8 b(.)40 b(The)29 b(FITS)0 5714 y(standard)j(only)g(supp)s(orts)g(2)h (and)g(4)g(b)m(yte)h(in)m(teger)f(data)h(t)m(yp)s(es,)g(so)f(CFITSIO)f (in)m(ternally)f(con)m(v)m(erts)j(b)s(et)m(w)m(een)p eop %%Page: 19 27 19 26 bop 0 299 a Fh(4.4.)72 b(SUPPOR)-8 b(T)30 b(F)m(OR)g(UNSIGNED)h (INTEGERS)f(AND)h(SIGNED)f(BYTES)942 b Fj(19)0 555 y(4)31 b(and)f(8)g(b)m(ytes)h(when)f(reading)f(or)h(writing)f(`long')h(in)m (tegers)h(on)f(Alpha/OSF)f(systems.)0 715 y(The)e(8-b)m(yte)i ('LONGLONG')f(in)m(teger)g(data)g(t)m(yp)s(e)g(is)e(supp)s(orted)g(on)i (most)f(platforms.)39 b(CFITSIO)26 b(de\014nes)h(the)0 828 y(LONGLONG)i(data)g(t)m(yp)s(e)g(to)h(b)s(e)e(equiv)-5 b(alen)m(t)29 b(to)g('long)g(long')g(on)f(most)i(Unix)d(platforms)h (and)g(on)h(Mac)h(OS-X.)0 941 y(Since)36 b(most)i(Windo)m(ws)e (compilers)g(don't)h(supp)s(ort)e(the)j('long)f(long')g(data)g(t)m(yp)s (e,)j(LONGLONG)d(is)f(de\014ned)0 1054 y(instead)e(to)h(b)s(e)f(equiv) -5 b(alen)m(t)33 b(to)i(')p 1141 1054 28 4 v 1175 1054 V 66 w(in)m(t64'.)54 b(If)34 b(the)g(compiler)f(do)s(es)h(not)h(supp)s (ort)d(a)j(8-b)m(yte)h(in)m(teger)f(data)g(t)m(yp)s(e)0 1167 y(then)d(LONGLONG)h(is)f(de\014ned)f(to)i(b)s(e)f(equiv)-5 b(alen)m(t)33 b(to)g('long'.)48 b(Note)34 b(that)f(the)g(C)f(format)h (sp)s(eci\014er)e(to)i(prin)m(t)0 1280 y(out)38 b(these)g(long)g(in)m (teger)g(v)-5 b(alues)37 b(is)g("\045lld")g(on)h(most)g(unix)e(mac)m (hines,)k(except)e(on)g(OSF)g(platforms)e(where)0 1393 y("\045ld")d(m)m(ust)g(b)s(e)f(used.)49 b(On)32 b(Windo)m(ws)g (platform)h(that)g(ha)m(v)m(e)i(the)p 2385 1393 V 2417 1393 V 99 w(in)m(t64)e(data)h(t)m(yp)s(e,)h(the)e(format)h(sp)s (eci\014er)0 1506 y(is)29 b("\045INT64d".)0 1666 y(When)23 b(dealing)f(with)g(the)i(FITS)f(b)m(yte)h(data)g(t)m(yp)s(e)f(it)g(is)g (imp)s(ortan)m(t)f(to)i(remem)m(b)s(er)f(that)h(the)g(ra)m(w)f(v)-5 b(alues)23 b(\(b)s(efore)0 1779 y(an)m(y)i(scaling)e(b)m(y)h(the)h (BSCALE)e(and)h(BZER)m(O,)g(or)h(TSCALn)d(and)i(TZER)m(On)f(k)m(eyw)m (ord)i(v)-5 b(alues\))24 b(in)f(b)m(yte)i(arra)m(ys)0 1892 y(\(BITPIX)37 b(=)f(8\))h(or)f(b)m(yte)i(columns)d(\(TF)m(ORMn)i (=)f('B'\))h(are)g(in)m(terpreted)f(as)h(unsigned)d(b)m(ytes)j(with)f (v)-5 b(alues)0 2005 y(ranging)33 b(from)h(0)g(to)h(255.)53 b(Some)34 b(C)g(compilers)f(de\014ne)g(a)h('c)m(har')h(v)-5 b(ariable)33 b(as)i(signed,)f(so)g(it)g(is)f(imp)s(ortan)m(t)g(to)0 2118 y(explicitly)28 b(declare)i(a)h(n)m(umeric)e(c)m(har)i(v)-5 b(ariable)29 b(as)i('unsigned)d(c)m(har')j(to)g(a)m(v)m(oid)g(an)m(y)g (am)m(biguit)m(y)0 2278 y(One)22 b(feature)h(of)g(the)g(CFITSIO)e (routines)h(is)f(that)j(they)f(can)g(op)s(erate)g(on)f(a)h(`X')h (\(bit\))e(column)g(in)f(a)i(binary)e(table)0 2391 y(as)33 b(though)f(it)g(w)m(ere)h(a)g(`B')g(\(b)m(yte\))h(column.)46 b(F)-8 b(or)33 b(example)f(a)h(`11X')h(data)f(t)m(yp)s(e)g(column)e (can)i(b)s(e)f(in)m(terpreted)0 2503 y(the)c(same)h(as)f(a)g(`2B')i (column)d(\(i.e.,)i(2)f(unsigned)e(8-bit)i(b)m(ytes\).)41 b(In)27 b(some)i(instances,)f(it)f(can)i(b)s(e)e(more)h(e\016cien)m(t)0 2616 y(to)j(read)f(and)g(write)g(whole)f(b)m(ytes)i(at)g(a)g(time,)f (rather)h(than)f(reading)f(or)i(writing)d(eac)m(h)k(individual)25 b(bit.)0 2777 y(The)36 b(complex)h(and)f(double)g(precision)f(complex)i (data)h(t)m(yp)s(es)f(are)g(not)g(directly)f(supp)s(orted)f(in)h(ANSI)g (C)h(so)0 2889 y(these)g(data)g(t)m(yp)s(es)f(should)e(b)s(e)i(in)m (terpreted)g(as)g(pairs)f(of)i(\015oat)g(or)f(double)f(v)-5 b(alues,)37 b(resp)s(ectiv)m(ely)-8 b(,)38 b(where)e(the)0 3002 y(\014rst)30 b(v)-5 b(alue)29 b(in)h(eac)m(h)h(pair)e(is)h(the)g (real)g(part,)h(and)e(the)i(second)f(is)g(the)g(imaginary)f(part.)0 3470 y Ff(4.4)135 b(Supp)t(ort)44 b(for)h(Unsigned)h(In)l(tegers)g(and) f(Signed)g(Bytes)0 3747 y Fj(Although)32 b(FITS)g(do)s(es)g(not)h (directly)f(supp)s(ort)f(unsigned)f(in)m(tegers)j(as)g(one)g(of)g(its)g (fundamen)m(tal)e(data)j(t)m(yp)s(es,)0 3860 y(FITS)27 b(can)h(still)e(b)s(e)h(used)g(to)i(e\016cien)m(tly)f(store)g(unsigned) e(in)m(teger)i(data)h(v)-5 b(alues)27 b(in)g(images)h(and)f(binary)f (tables.)0 3973 y(The)42 b(con)m(v)m(en)m(tion)i(used)e(in)f(FITS)h (\014les)g(is)f(to)j(store)f(the)g(unsigned)d(in)m(tegers)j(as)g (signed)f(in)m(tegers)h(with)e(an)0 4086 y(asso)s(ciated)33 b(o\013set)g(\(sp)s(eci\014ed)e(b)m(y)h(the)g(BZER)m(O)g(or)g(TZER)m (On)f(k)m(eyw)m(ord\).)47 b(F)-8 b(or)33 b(example,)f(to)h(store)g (unsigned)0 4199 y(16-bit)f(in)m(teger)g(v)-5 b(alues)31 b(in)f(a)i(FITS)f(image)h(the)f(image)h(w)m(ould)f(b)s(e)f(de\014ned)h (as)h(a)g(signed)e(16-bit)i(in)m(teger)g(\(with)0 4312 y(BITPIX)d(k)m(eyw)m(ord)g(=)g(SHOR)-8 b(T)p 1132 4312 V 32 w(IMG)30 b(=)e(16\))j(with)c(the)j(k)m(eyw)m(ords)f(BSCALE)f(=)h (1.0)h(and)f(BZER)m(O)g(=)f(32768.)0 4425 y(Th)m(us)34 b(the)h(unsigned)e(v)-5 b(alues)34 b(of)h(0,)i(32768,)h(and)d(65535,)j (for)d(example,)h(are)f(ph)m(ysically)e(stored)i(in)f(the)h(FITS)0 4538 y(image)k(as)f(-32768,)43 b(0,)e(and)d(32767,)k(resp)s(ectiv)m (ely;)g(CFITSIO)37 b(automatically)h(adds)f(the)i(BZER)m(O)f(o\013set)h (to)0 4650 y(these)g(v)-5 b(alues)38 b(when)g(they)g(are)h(read.)65 b(Similarly)-8 b(,)38 b(in)f(the)i(case)h(of)e(unsigned)f(32-bit)i(in)m (tegers)f(the)h(BITPIX)0 4763 y(k)m(eyw)m(ord)c(w)m(ould)e(b)s(e)h (equal)g(to)i(LONG)p 1392 4763 V 32 w(IMG)f(=)g(32)g(and)f(BZER)m(O)g (w)m(ould)g(b)s(e)g(equal)g(to)h(2147483648)k(\(i.e.)54 b(2)0 4876 y(raised)29 b(to)i(the)g(31st)g(p)s(o)m(w)m(er\).)0 5036 y(The)j(CFITSIO)g(in)m(terface)h(routines)f(will)e(e\016cien)m (tly)j(and)f(transparen)m(tly)h(apply)e(the)i(appropriate)f(o\013set)i (in)0 5149 y(these)29 b(cases)h(so)f(in)f(general)h(application)e (programs)i(do)g(not)g(need)f(to)i(b)s(e)e(concerned)h(with)f(ho)m(w)h (the)g(unsigned)0 5262 y(v)-5 b(alues)43 b(are)i(actually)f(stored)g (in)e(the)j(FITS)e(\014le.)81 b(As)44 b(a)g(con)m(v)m(enience)i(for)d (users,)k(CFITSIO)c(has)h(sev)m(eral)0 5375 y(prede\014ned)19 b(constan)m(ts)j(for)f(the)g(v)-5 b(alue)20 b(of)h(BITPIX)g(\(USHOR)-8 b(T)p 2189 5375 V 33 w(IMG,)21 b(ULONG)p 2790 5375 V 33 w(IMG\))h(and)e(for)h(the)g(TF)m(ORMn)0 5488 y(v)-5 b(alue)35 b(in)f(the)i(case)g(of)g(binary)e(tables)h(\(`U')i(and)e (`V'\))h(whic)m(h)e(programmers)h(can)h(use)f(when)g(creating)h(FITS)0 5601 y(\014les)i(con)m(taining)g(unsigned)f(in)m(teger)i(v)-5 b(alues.)65 b(The)39 b(follo)m(wing)e(co)s(de)i(fragmen)m(t)g (illustrates)e(ho)m(w)i(to)h(write)e(a)0 5714 y(FITS)30 b(1-D)h(primary)e(arra)m(y)h(of)h(unsigned)d(16-bit)j(in)m(tegers:)p eop %%Page: 20 28 20 27 bop 0 299 a Fj(20)1763 b Fh(CHAPTER)29 b(4.)112 b(PR)m(OGRAMMING)32 b(GUIDELINES)286 555 y Fe(unsigned)46 b(short)g(uarray[100];)286 668 y(int)h(naxis,)f(status;)286 781 y(long)h(naxes[10],)e(group,)h(firstelem,)f(nelements;)334 894 y(...)286 1007 y(status)h(=)i(0;)286 1120 y(naxis)f(=)g(1;)286 1233 y(naxes[0])f(=)h(100;)286 1346 y(fits_create_img\(fptr,)42 b(USHORT_IMG,)j(naxis,)h(naxes,)g(&status\);)286 1571 y(firstelem)g(=)h(1;)286 1684 y(nelements)f(=)h(100;)286 1797 y(fits_write_img\(fptr,)c(TUSHORT,)i(firstelem,)g(nelements,)1241 1910 y(uarray,)h(&status\);)334 2023 y(...)0 2264 y Fj(In)40 b(the)h(ab)s(o)m(v)m(e)i(example,)g(the)f(2nd)e(parameter)h(in)f (\014ts)p 1998 2264 28 4 v 33 w(create)p 2267 2264 V 34 w(img)g(tells)g(CFITSIO)g(to)i(write)e(the)h(header)0 2377 y(k)m(eyw)m(ords)34 b(appropriate)f(for)g(an)g(arra)m(y)i(of)e (16-bit)h(unsigned)e(in)m(tegers)i(\(i.e.,)h(BITPIX)e(=)g(16)i(and)e (BZER)m(O)g(=)0 2490 y(32768\).)41 b(Then)23 b(the)h(\014ts)p 834 2490 V 32 w(write)p 1069 2490 V 32 w(img)g(routine)f(writes)f(the)j (arra)m(y)f(of)g(unsigned)e(short)h(in)m(tegers)h(\(uarra)m(y\))h(in)m (to)f(the)0 2603 y(primary)f(arra)m(y)i(of)g(the)g(FITS)f(\014le.)38 b(Similarly)-8 b(,)23 b(a)i(32-bit)h(unsigned)c(in)m(teger)j(image)h (ma)m(y)f(b)s(e)f(created)i(b)m(y)f(setting)0 2716 y(the)34 b(second)f(parameter)h(in)e(\014ts)p 1130 2716 V 33 w(create)p 1399 2716 V 34 w(img)h(equal)g(to)h(`ULONG)p 2330 2716 V 33 w(IMG')g(and)f(b)m(y)h(calling)d(the)j(\014ts)p 3491 2716 V 33 w(write)p 3727 2716 V 32 w(img)0 2829 y(routine)i(with)f(the)i(second)f(parameter)h(=)f(TULONG)h(to)g(write)f (the)g(arra)m(y)h(of)g(unsigned)e(long)h(image)h(pixel)0 2942 y(v)-5 b(alues.)0 3102 y(An)27 b(analogous)g(set)g(of)g(routines)f (are)h(a)m(v)-5 b(ailable)27 b(for)f(reading)g(or)h(writing)e(unsigned) g(in)m(teger)i(v)-5 b(alues)27 b(and)f(signed)0 3215 y(b)m(yte)i(v)-5 b(alues)27 b(in)g(a)h(FITS)f(binary)f(table)i (extension.)39 b(When)28 b(sp)s(ecifying)d(the)j(TF)m(ORMn)g(k)m(eyw)m (ord)g(v)-5 b(alue)27 b(whic)m(h)0 3328 y(de\014nes)36 b(the)h(format)g(of)g(a)h(column,)f(CFITSIO)e(recognized)j(3)f (additional)e(data)i(t)m(yp)s(e)g(co)s(des)g(b)s(esides)e(those)0 3440 y(already)29 b(de\014ned)g(in)f(the)i(FITS)f(standard:)40 b(`U')30 b(meaning)f(a)h(16-bit)g(unsigned)e(in)m(teger)i(column,)f (`V')h(for)g(a)g(32-)0 3553 y(bit)25 b(unsigned)e(in)m(teger)j(column,) g(and)f('S')g(for)g(a)h(signed)f(b)m(yte)h(column.)38 b(These)25 b(non-standard)g(data)h(t)m(yp)s(e)g(co)s(des)0 3666 y(are)36 b(not)g(actually)g(written)f(in)m(to)g(the)h(FITS)g (\014le)e(but)i(instead)f(are)h(just)f(used)g(in)m(ternally)f(within)f (CFITSIO.)0 3779 y(The)d(follo)m(wing)f(co)s(de)h(fragmen)m(t)h (illustrates)e(ho)m(w)h(to)h(use)f(these)h(features:)286 4020 y Fe(unsigned)46 b(short)g(uarray[100];)286 4133 y(unsigned)g(int)95 b(varray[100];)286 4359 y(int)47 b(colnum,)f(tfields,)g(status;)286 4472 y(long)h(nrows,)f(firstrow,)f (firstelem,)g(nelements,)g(pcount;)286 4698 y(char)i(extname[])e(=)j ("Test_table";)521 b(/*)47 b(extension)f(name)g(*/)286 4924 y(/*)i(define)e(the)h(name,)f(data)h(type,)f(and)h(physical)e (units)i(for)g(the)g(2)g(columns)f(*/)286 5036 y(char)h(*ttype[])f(=)h ({)g("Col_1",)f("Col_2",)g("Col_3")f(};)286 5149 y(char)i(*tform[])f(=) h({)g("1U",)285 b("1V",)190 b("1S"};)94 b(/*)47 b(special)f(CFITSIO)g (codes)g(*/)286 5262 y(char)h(*tunit[])f(=)h({)g(")h(",)381 b(")48 b(",)190 b(")47 b(")h(};)334 5375 y(...)525 5601 y(/*)f(write)g(the)f(header)h(keywords)e(*/)286 5714 y(status)94 b(=)48 b(0;)p eop %%Page: 21 29 21 28 bop 0 299 a Fh(4.5.)72 b(DEALING)31 b(WITH)f(CHARA)m(CTER)g (STRINGS)1816 b Fj(21)286 555 y Fe(nrows)142 b(=)48 b(1;)286 668 y(tfields)e(=)i(3)286 781 y(pcount)94 b(=)48 b(0;)286 894 y(fits_create_tbl\(fptr,)42 b(BINARY_TBL,)j(nrows,)h(tfields,)g (ttype,)g(tform,)764 1007 y(tunit,)g(extname,)f(&status\);)525 1233 y(/*)i(write)g(the)f(unsigned)g(shorts)g(to)h(the)g(1st)g(column)f (*/)286 1346 y(colnum)190 b(=)47 b(1;)286 1458 y(firstrow)94 b(=)47 b(1;)286 1571 y(firstelem)f(=)h(1;)286 1684 y(nelements)f(=)h (100;)286 1797 y(fits_write_col\(fptr,)c(TUSHORT,)i(colnum,)h (firstrow,)f(firstelem,)668 1910 y(nelements,)g(uarray,)h(&status\);) 525 2136 y(/*)h(now)g(write)f(the)h(unsigned)f(longs)g(to)h(the)g(2nd)g (column)f(*/)286 2249 y(colnum)190 b(=)47 b(2;)286 2362 y(fits_write_col\(fptr,)c(TUINT,)j(colnum,)g(firstrow,)f(firstelem,)668 2475 y(nelements,)g(varray,)h(&status\);)334 2588 y(...)0 2865 y Fj(Note)22 b(that)g(the)f(non-standard)f(TF)m(ORM)h(v)-5 b(alues)20 b(for)h(the)g(3)g(columns,)h(`U')f(and)g(`V',)h(tell)e (CFITSIO)f(to)j(write)e(the)0 2978 y(k)m(eyw)m(ords)27 b(appropriate)e(for)h(unsigned)e(16-bit)j(and)e(unsigned)g(32-bit)h(in) m(tegers,)i(resp)s(ectiv)m(ely)d(\(i.e.,)j(TF)m(ORMn)0 3091 y(=)39 b('1I')i(and)e(TZER)m(On)f(=)h(32678)j(for)e(unsigned)d (16-bit)j(in)m(tegers,)j(and)c(TF)m(ORMn)h(=)f('1J')h(and)f(TZER)m(On)0 3204 y(=)c(2147483648)40 b(for)35 b(unsigned)e(32-bit)i(in)m(tegers\).) 56 b(The)35 b('S')g(TF)m(ORMn)g(v)-5 b(alue)35 b(tells)g(CFITSIO)e(to)j (write)f(the)0 3317 y(k)m(eyw)m(ords)30 b(appropriate)f(for)h(a)g (signed)f(8-bit)h(b)m(yte)g(column)f(with)f(TF)m(ORMn)i(=)g('1B')h(and) e(TZER)m(On)g(=)g(-128.)0 3430 y(The)h(calls)f(to)j(\014ts)p 628 3430 28 4 v 32 w(write)p 863 3430 V 32 w(col)e(then)g(write)g(the)h (arra)m(ys)f(of)h(unsigned)d(in)m(teger)j(v)-5 b(alues)30 b(to)h(the)f(columns.)0 3784 y Ff(4.5)135 b(Dealing)47 b(with)e(Character)h(Strings)0 4039 y Fj(The)36 b(c)m(haracter)j (string)c(v)-5 b(alues)37 b(in)e(a)i(FITS)f(header)h(or)g(in)e(an)i (ASCI)s(I)e(column)h(in)f(a)j(FITS)e(table)g(extension)0 4152 y(are)j(generally)g(padded)f(out)h(with)f(non-signi\014can)m(t)g (space)h(c)m(haracters)i(\(ASCI)s(I)d(32\))i(to)g(\014ll)d(up)h(the)h (header)0 4264 y(record)33 b(or)h(the)f(column)g(width.)48 b(When)33 b(reading)g(a)h(FITS)e(string)h(v)-5 b(alue,)34 b(the)f(CFITSIO)f(routines)h(will)d(strip)0 4377 y(o\013)38 b(these)f(non-signi\014can)m(t)f(trailing)f(spaces)i(and)g(will)d (return)i(a)i(n)m(ull-terminated)d(string)h(v)-5 b(alue)36 b(con)m(taining)0 4490 y(only)d(the)h(signi\014can)m(t)e(c)m (haracters.)52 b(Leading)33 b(spaces)h(in)f(a)h(FITS)f(string)f(are)i (considered)f(signi\014can)m(t.)50 b(If)33 b(the)0 4603 y(string)h(con)m(tains)h(all)f(blanks,)h(then)f(CFITSIO)g(will)e (return)i(a)h(single)e(blank)h(c)m(haracter,)k(i.e,)e(the)f(\014rst)f (blank)0 4716 y(is)29 b(considered)f(to)j(b)s(e)e(signi\014can)m(t,)g (since)g(it)g(distinguishes)e(the)j(string)e(from)i(a)g(n)m(ull)d(or)j (unde\014ned)e(string,)h(but)0 4829 y(the)i(remaining)d(trailing)g (spaces)j(are)g(not)g(signi\014can)m(t.)0 4989 y(Similarly)-8 b(,)37 b(when)g(writing)f(string)h(v)-5 b(alues)37 b(to)i(a)g(FITS)e (\014le)g(the)h(CFITSIO)f(routines)g(exp)s(ect)h(to)h(get)g(a)g(n)m (ull-)0 5102 y(terminated)32 b(string)g(as)h(input;)f(CFITSIO)f(will)f (pad)i(the)h(string)f(with)f(blanks)g(if)h(necessary)h(when)f(writing)e (it)0 5215 y(to)h(the)g(FITS)e(\014le.)0 5375 y(When)j(calling)f (CFITSIO)g(routines)h(that)h(return)e(a)i(c)m(haracter)h(string)e(it)g (is)f(vital)h(that)h(the)g(size)f(of)h(the)g(c)m(har)0 5488 y(arra)m(y)38 b(b)s(e)g(large)g(enough)f(to)i(hold)d(the)i(en)m (tire)g(string)f(of)h(c)m(haracters,)k(otherwise)37 b(CFITSIO)f(will)f (o)m(v)m(erwrite)0 5601 y(whatev)m(er)g(memory)e(lo)s(cations)g(follo)m (w)g(the)h(c)m(har)h(arra)m(y)-8 b(,)35 b(p)s(ossibly)c(causing)i(the)h (program)g(to)g(execute)h(incor-)0 5714 y(rectly)-8 b(.)41 b(This)29 b(t)m(yp)s(e)h(of)h(error)f(can)h(b)s(e)f(di\016cult)e(to)j (debug,)f(so)h(programmers)f(should)e(alw)m(a)m(ys)j(ensure)f(that)h (the)p eop %%Page: 22 30 22 29 bop 0 299 a Fj(22)1763 b Fh(CHAPTER)29 b(4.)112 b(PR)m(OGRAMMING)32 b(GUIDELINES)0 555 y Fj(c)m(har)27 b(arra)m(ys)g(are)g(allo)s(cated)g(enough)f(space)i(to)f(hold)f(the)g (longest)h(p)s(ossible)e(string,)h Fi(including)i Fj(the)f(terminat-)0 668 y(ing)j(NULL)h(c)m(haracter.)45 b(The)30 b(\014tsio.h)g(\014le)h (con)m(tains)g(the)g(follo)m(wing)f(de\014ned)g(constan)m(ts)i(whic)m (h)e(programmers)0 781 y(are)h(strongly)f(encouraged)h(to)g(use)f (whenev)m(er)g(they)h(are)f(allo)s(cating)g(space)h(for)f(c)m(har)h (arra)m(ys:)0 1025 y Fe(#define)46 b(FLEN_FILENAME)e(1025)j(/*)g(max)g (length)f(of)h(a)g(filename)f(*/)0 1138 y(#define)g(FLEN_KEYWORD)140 b(72)95 b(/*)47 b(max)g(length)f(of)h(a)g(keyword)94 b(*/)0 1251 y(#define)46 b(FLEN_CARD)284 b(81)95 b(/*)47 b(length)f(of)h(a)h(FITS)e(header)g(card)h(*/)0 1364 y(#define)f(FLEN_VALUE)236 b(71)95 b(/*)47 b(max)g(length)f(of)h(a)g (keyword)f(value)h(string)f(*/)0 1477 y(#define)g(FLEN_COMMENT)140 b(73)95 b(/*)47 b(max)g(length)f(of)h(a)g(keyword)f(comment)g(string)g (*/)0 1590 y(#define)g(FLEN_ERRMSG)188 b(81)95 b(/*)47 b(max)g(length)f(of)h(a)g(CFITSIO)f(error)h(message)e(*/)0 1703 y(#define)h(FLEN_STATUS)188 b(31)95 b(/*)47 b(max)g(length)f(of)h (a)g(CFITSIO)f(status)g(text)h(string)f(*/)0 1947 y Fj(F)-8 b(or)23 b(example,)g(when)e(declaring)g(a)h(c)m(har)g(arra)m(y)h(to)f (hold)f(the)h(v)-5 b(alue)21 b(string)g(of)h(FITS)f(k)m(eyw)m(ord,)k (use)c(the)h(follo)m(wing)0 2060 y(statemen)m(t:)191 2304 y Fe(char)47 b(value[FLEN_VALUE];)0 2548 y Fj(Note)41 b(that)f(FLEN)p 686 2548 28 4 v 33 w(KEYW)m(ORD)g(is)e(longer)h(than)g (needed)g(for)g(the)h(nominal)d(8-c)m(haracter)42 b(k)m(eyw)m(ord)e (name)0 2661 y(b)s(ecause)30 b(the)h(HIERAR)m(CH)f(con)m(v)m(en)m(tion) i(supp)s(orts)c(longer)i(k)m(eyw)m(ord)h(names.)0 2992 y Ff(4.6)135 b(Implicit)46 b(Data)g(T)l(yp)t(e)f(Con)l(v)l(ersion)0 3242 y Fj(The)29 b(CFITSIO)e(routines)h(that)i(read)f(and)f(write)h(n)m (umerical)e(data)j(can)g(p)s(erform)d(implicit)f(data)k(t)m(yp)s(e)f (con)m(v)m(er-)0 3355 y(sion.)38 b(This)24 b(means)i(that)g(the)g(data) g(t)m(yp)s(e)g(of)g(the)g(v)-5 b(ariable)24 b(or)i(arra)m(y)g(in)e(the) i(program)g(do)s(es)f(not)h(need)f(to)i(b)s(e)e(the)0 3468 y(same)g(as)f(the)h(data)g(t)m(yp)s(e)g(of)f(the)h(v)-5 b(alue)24 b(in)f(the)h(FITS)g(\014le.)38 b(Data)26 b(t)m(yp)s(e)f(con)m (v)m(ersion)f(is)g(supp)s(orted)e(for)i(n)m(umerical)0 3581 y(and)37 b(string)f(data)h(t)m(yp)s(es)h(\(if)e(the)h(string)f (con)m(tains)i(a)f(v)-5 b(alid)36 b(n)m(um)m(b)s(er)g(enclosed)g(in)g (quotes\))i(when)e(reading)h(a)0 3694 y(FITS)30 b(header)h(k)m(eyw)m (ord)g(v)-5 b(alue)30 b(and)g(for)h(n)m(umeric)f(v)-5 b(alues)30 b(when)g(reading)g(or)g(writing)f(v)-5 b(alues)30 b(in)g(the)h(primary)0 3807 y(arra)m(y)24 b(or)g(a)h(table)e(column.)38 b(CFITSIO)22 b(returns)h(status)h(=)f(NUM)p 2267 3807 V 34 w(O)m(VERFLO)m(W)i(if)d(the)i(con)m(v)m(erted)i(data)e(v)-5 b(alue)0 3920 y(exceeds)33 b(the)g(range)g(of)g(the)f(output)g(data)i (t)m(yp)s(e.)47 b(Implicit)30 b(data)j(t)m(yp)s(e)g(con)m(v)m(ersion)g (is)e(not)i(supp)s(orted)d(within)0 4032 y(binary)f(tables)h(for)g (string,)f(logical,)i(complex,)f(or)g(double)f(complex)h(data)h(t)m(yp) s(es.)0 4193 y(In)g(addition,)f(an)m(y)h(table)g(column)f(ma)m(y)i(b)s (e)f(read)g(as)h(if)e(it)h(con)m(tained)g(string)f(v)-5 b(alues.)43 b(In)31 b(the)g(case)i(of)e(n)m(umeric)0 4306 y(columns)e(the)i(returned)e(string)g(will)f(b)s(e)i(formatted)h (using)d(the)j(TDISPn)e(displa)m(y)g(format)h(if)g(it)g(exists.)0 4637 y Ff(4.7)135 b(Data)46 b(Scaling)0 4887 y Fj(When)38 b(reading)e(n)m(umerical)h(data)h(v)-5 b(alues)37 b(in)f(the)i(primary) e(arra)m(y)i(or)g(a)g(table)g(column,)h(the)e(v)-5 b(alues)37 b(will)f(b)s(e)0 5000 y(scaled)h(automatically)h(b)m(y)f(the)g(BSCALE)g (and)g(BZER)m(O)g(\(or)h(TSCALn)e(and)h(TZER)m(On\))f(header)h(v)-5 b(alues)37 b(if)0 5113 y(they)31 b(are)f(presen)m(t)h(in)e(the)h (header.)41 b(The)30 b(scaled)g(data)h(that)g(is)e(returned)h(to)h(the) f(reading)g(program)g(will)e(ha)m(v)m(e)382 5357 y Fe(output)46 b(value)g(=)i(\(FITS)e(value\))g(*)i(BSCALE)e(+)h(BZERO)0 5601 y Fj(\(a)30 b(corresp)s(onding)d(form)m(ula)h(using)g(TSCALn)f (and)i(TZER)m(On)e(is)h(used)h(when)f(reading)g(from)h(table)g (columns\).)0 5714 y(In)i(the)i(case)g(of)f(in)m(teger)g(output)g(v)-5 b(alues)31 b(the)i(\015oating)f(p)s(oin)m(t)f(scaled)g(v)-5 b(alue)32 b(is)f(truncated)h(to)h(an)f(in)m(teger)g(\(not)p eop %%Page: 23 31 23 30 bop 0 299 a Fh(4.8.)72 b(SUPPOR)-8 b(T)30 b(F)m(OR)g(IEEE)g (SPECIAL)f(V)-10 b(ALUES)1863 b Fj(23)0 555 y(rounded)35 b(to)j(the)f(nearest)h(in)m(teger\).)61 b(The)36 b(\014ts)p 1673 555 28 4 v 32 w(set)p 1816 555 V 34 w(bscale)h(and)f(\014ts)p 2430 555 V 32 w(set)p 2573 555 V 34 w(tscale)h(routines)f(\(describ)s (ed)f(in)h(the)0 668 y(`Adv)-5 b(anced')29 b(c)m(hapter\))h(ma)m(y)g(b) s(e)e(used)h(to)g(o)m(v)m(erride)h(the)f(scaling)f(parameters)h (de\014ned)f(in)g(the)h(header)g(\(e.g.,)i(to)0 781 y(turn)e(o\013)i (the)g(scaling)e(so)i(that)g(the)f(program)g(can)h(read)f(the)h(ra)m(w) f(unscaled)g(v)-5 b(alues)29 b(from)h(the)h(FITS)e(\014le\).)0 941 y(When)44 b(writing)f(n)m(umerical)g(data)i(to)g(the)g(primary)e (arra)m(y)i(or)f(to)h(a)g(table)g(column)e(the)i(data)g(v)-5 b(alues)44 b(will)0 1054 y(generally)27 b(b)s(e)h(automatically)g(in)m (v)m(ersely)g(scaled)g(b)m(y)g(the)g(v)-5 b(alue)28 b(of)g(the)h (BSCALE)e(and)h(BZER)m(O)g(\(or)h(TSCALn)0 1167 y(and)35 b(TZER)m(On\))f(k)m(eyw)m(ord)i(v)-5 b(alues)34 b(if)h(they)g(they)g (exist)h(in)e(the)h(header.)55 b(These)35 b(k)m(eyw)m(ords)h(m)m(ust)f (ha)m(v)m(e)i(b)s(een)0 1280 y(written)30 b(to)i(the)g(header)f(b)s (efore)g(an)m(y)g(data)h(is)f(written)f(for)h(them)g(to)h(ha)m(v)m(e)h (an)m(y)e(immediate)g(e\013ect.)45 b(One)30 b(ma)m(y)0 1393 y(also)g(use)h(the)f(\014ts)p 623 1393 V 33 w(set)p 767 1393 V 33 w(bscale)h(and)e(\014ts)p 1367 1393 V 33 w(set)p 1511 1393 V 33 w(tscale)i(routines)f(to)h(de\014ne)f(or)g(o)m (v)m(erride)h(the)g(scaling)e(k)m(eyw)m(ords)i(in)0 1506 y(the)e(header)g(\(e.g.,)i(to)e(turn)f(o\013)h(the)g(scaling)f(so)h (that)h(the)f(program)f(can)h(write)f(the)h(ra)m(w)g(unscaled)f(v)-5 b(alues)28 b(in)m(to)0 1619 y(the)e(FITS)g(\014le\).)39 b(If)25 b(scaling)g(is)h(p)s(erformed,)f(the)i(in)m(v)m(erse)f(scaled)g (output)f(v)-5 b(alue)26 b(that)h(is)e(written)g(in)m(to)h(the)h(FITS)0 1732 y(\014le)i(will)f(ha)m(v)m(e)430 1992 y Fe(FITS)46 b(value)h(=)g(\(\(input)f(value\))g(-)h(BZERO\))f(/)i(BSCALE)0 2252 y Fj(\(a)39 b(corresp)s(onding)c(form)m(ula)i(using)g(TSCALn)f (and)h(TZER)m(On)g(is)g(used)g(when)f(writing)g(to)j(table)f (columns\).)0 2365 y(Rounding)33 b(to)j(the)g(nearest)g(in)m(teger,)h (rather)e(than)g(truncation,)i(is)d(p)s(erformed)g(when)g(writing)f(in) m(teger)j(data)0 2478 y(t)m(yp)s(es)30 b(to)i(the)e(FITS)g(\014le.)0 2812 y Ff(4.8)135 b(Supp)t(ort)44 b(for)h(IEEE)h(Sp)t(ecial)f(V)-11 b(alues)0 3062 y Fj(The)26 b(ANSI/IEEE-754)h(\015oating-p)s(oin)m(t)f (n)m(um)m(b)s(er)f(standard)g(de\014nes)h(certain)g(sp)s(ecial)f(v)-5 b(alues)25 b(that)i(are)g(used)e(to)0 3175 y(represen)m(t)j(suc)m(h)g (quan)m(tities)f(as)h(Not-a-Num)m(b)s(er)h(\(NaN\),)h(denormalized,)d (under\015o)m(w,)g(o)m(v)m(er\015o)m(w,)j(and)d(in\014nit)m(y)-8 b(.)0 3288 y(\(See)29 b(the)f(App)s(endix)d(in)i(the)h(NOST)g(FITS)f (standard)g(or)h(the)g(NOST)g(FITS)f(User's)h(Guide)f(for)h(a)g(list)f (of)h(these)0 3401 y(v)-5 b(alues\).)54 b(The)34 b(CFITSIO)f(routines)h (that)h(read)g(\015oating)f(p)s(oin)m(t)g(data)i(in)d(FITS)h(\014les)g (recognize)h(these)h(IEEE)0 3514 y(sp)s(ecial)22 b(v)-5 b(alues)24 b(and)f(b)m(y)g(default)g(in)m(terpret)h(the)g(o)m(v)m (er\015o)m(w)h(and)e(in\014nit)m(y)e(v)-5 b(alues)24 b(as)g(b)s(eing)e(equiv)-5 b(alen)m(t)23 b(to)i(a)f(NaN,)0 3627 y(and)36 b(con)m(v)m(ert)i(the)e(under\015o)m(w)f(and)h (denormalized)f(v)-5 b(alues)35 b(in)m(to)i(zeros.)59 b(In)36 b(some)g(cases)i(programmers)d(ma)m(y)0 3740 y(w)m(an)m(t)d(access)h(to)g(the)e(ra)m(w)h(IEEE)f(v)-5 b(alues,)31 b(without)g(an)m(y)h(mo)s(di\014cation)e(b)m(y)h(CFITSIO.)f (This)g(can)i(b)s(e)f(done)g(b)m(y)0 3853 y(calling)26 b(the)j(\014ts)p 567 3853 V 32 w(read)p 771 3853 V 33 w(img)e(or)h(\014ts)p 1209 3853 V 33 w(read)p 1414 3853 V 32 w(col)g(routines)f(while)f(sp)s(ecifying)g(0.0)j(as)f(the)g(v)-5 b(alue)28 b(of)g(the)g(NULL)-10 b(V)g(AL)0 3966 y(parameter.)59 b(This)35 b(will)e(force)k(CFITSIO)e(to)i(simply)d(pass)i(the)h(IEEE)f (v)-5 b(alues)35 b(through)h(to)h(the)g(application)0 4079 y(program)31 b(without)f(an)m(y)i(mo)s(di\014cation.)42 b(This)29 b(is)i(not)g(fully)e(supp)s(orted)h(on)h(V)-10 b(AX/VMS)32 b(mac)m(hines,)f(ho)m(w)m(ev)m(er,)0 4192 y(where)f(there)g(is)g(no)g(easy)h(w)m(a)m(y)g(to)h(b)m(ypass)e(the)g (default)g(in)m(terpretation)f(of)i(the)g(IEEE)e(sp)s(ecial)g(v)-5 b(alues.)0 4526 y Ff(4.9)135 b(Error)46 b(Status)f(V)-11 b(alues)45 b(and)g(the)g(Error)g(Message)h(Stac)l(k)0 4776 y Fj(Nearly)35 b(all)f(the)i(CFITSIO)e(routines)g(return)g(an)h (error)g(status)h(v)-5 b(alue)34 b(in)g(2)i(w)m(a)m(ys:)51 b(as)36 b(the)f(v)-5 b(alue)35 b(of)h(the)f(last)0 4889 y(parameter)29 b(in)e(the)h(function)f(call,)i(and)f(as)g(the)h (returned)e(v)-5 b(alue)28 b(of)g(the)h(function)e(itself.)39 b(This)26 b(pro)m(vides)i(some)0 5002 y(\015exibilit)m(y)33 b(in)h(the)i(w)m(a)m(y)h(programmers)e(can)h(test)h(if)e(an)g(error)h (o)s(ccurred,)g(as)g(illustrated)e(in)g(the)i(follo)m(wing)f(2)0 5115 y(co)s(de)c(fragmen)m(ts:)191 5375 y Fe(if)47 b(\()h (fits_write_record\(fptr,)41 b(card,)46 b(&status\))g(\))430 5488 y(printf\(")f(Error)h(occurred)g(while)g(writing)g(keyword."\);)0 5714 y(or,)p eop %%Page: 24 32 24 31 bop 0 299 a Fj(24)1763 b Fh(CHAPTER)29 b(4.)112 b(PR)m(OGRAMMING)32 b(GUIDELINES)191 668 y Fe(fits_write_record\(fptr,) 41 b(card,)47 b(&status\);)191 781 y(if)g(\()h(status)e(\))430 894 y(printf\(")f(Error)h(occurred)g(while)g(writing)g(keyword."\);)0 1109 y Fj(A)27 b(listing)e(of)j(all)e(the)h(CFITSIO)f(status)i(co)s(de) f(v)-5 b(alues)27 b(is)f(giv)m(en)h(at)h(the)g(end)e(of)i(this)e(do)s (cumen)m(t.)39 b(Programmers)0 1222 y(are)33 b(encouraged)g(to)g(use)f (the)h(sym)m(b)s(olic)d(mnemonics)h(\(de\014ned)h(in)f(\014tsio.h\))h (rather)g(than)g(the)h(actual)g(in)m(teger)0 1335 y(status)e(v)-5 b(alues)29 b(to)j(impro)m(v)m(e)e(the)g(readabilit)m(y)f(of)i(their)e (co)s(de.)0 1495 y(The)j(CFITSIO)f(library)e(uses)j(an)g(`inherited)f (status')i(con)m(v)m(en)m(tion)g(for)f(the)h(status)f(parameter)h(whic) m(h)e(means)0 1608 y(that)37 b(if)e(a)i(routine)e(is)h(called)f(with)g (a)i(p)s(ositiv)m(e)e(input)g(v)-5 b(alue)36 b(of)g(the)h(status)f (parameter)h(as)g(input,)f(then)g(the)0 1721 y(routine)i(will)d(exit)k (immediately)e(without)g(c)m(hanging)i(the)f(v)-5 b(alue)38 b(of)h(the)g(status)g(parameter.)65 b(Th)m(us,)40 b(if)e(one)0 1834 y(passes)24 b(the)h(status)g(v)-5 b(alue)24 b(returned)g(from)g (eac)m(h)i(CFITSIO)d(routine)g(as)i(input)e(to)i(the)g(next)g(CFITSIO)e (routine,)0 1947 y(then)28 b(whenev)m(er)g(an)g(error)g(is)g(detected)h (all)f(further)f(CFITSIO)f(pro)s(cessing)h(will)f(cease.)42 b(This)26 b(con)m(v)m(en)m(tion)k(can)0 2060 y(simplify)f(the)k(error)f (c)m(hec)m(king)i(in)d(application)g(programs)h(b)s(ecause)h(it)f(is)g (not)h(necessary)g(to)g(c)m(hec)m(k)i(the)d(v)-5 b(alue)0 2173 y(of)30 b(the)g(status)h(parameter)f(after)h(ev)m(ery)g(single)d (CFITSIO)h(routine)g(call.)40 b(If)30 b(a)g(program)g(con)m(tains)g(a)h (sequence)0 2285 y(of)d(sev)m(eral)h(CFITSIO)e(calls,)h(one)g(can)h (just)e(c)m(hec)m(k)j(the)f(status)f(v)-5 b(alue)28 b(after)h(the)f (last)g(call.)39 b(Since)28 b(the)g(returned)0 2398 y(status)33 b(v)-5 b(alues)32 b(are)h(generally)f(distinctiv)m(e,)g(it)h(should)d (b)s(e)j(p)s(ossible)d(to)j(determine)f(whic)m(h)g(routine)g (originally)0 2511 y(returned)d(the)i(error)f(status.)0 2671 y(CFITSIO)c(also)h(main)m(tains)g(an)g(in)m(ternal)f(stac)m(k)j (of)f(error)f(messages)h(\(80-c)m(haracter)j(maxim)m(um)26 b(length\))h(whic)m(h)0 2784 y(in)35 b(man)m(y)h(cases)h(pro)m(vide)e (a)h(more)g(detailed)g(explanation)f(of)h(the)g(cause)h(of)f(the)g (error)g(than)f(is)g(pro)m(vided)g(b)m(y)0 2897 y(the)40 b(error)e(status)i(n)m(um)m(b)s(er)e(alone.)68 b(It)39 b(is)g(recommended)g(that)g(the)h(error)f(message)h(stac)m(k)h(b)s(e)e (prin)m(ted)f(out)0 3010 y(whenev)m(er)h(a)g(program)g(detects)h(a)f (CFITSIO)e(error.)66 b(The)38 b(function)g(\014ts)p 2653 3010 28 4 v 32 w(rep)s(ort)p 2931 3010 V 32 w(error)h(will)d(prin)m(t)i (out)h(the)0 3123 y(en)m(tire)30 b(error)f(message)h(stac)m(k,)i(or)d (alternativ)m(ely)h(one)g(ma)m(y)g(call)f(\014ts)p 2376 3123 V 32 w(read)p 2580 3123 V 33 w(errmsg)g(to)h(get)h(the)f(error)f (messages)0 3236 y(one)i(at)g(a)g(time.)0 3563 y Ff(4.10)136 b(V)-11 b(ariable-Length)45 b(Arra)l(ys)g(in)g(Binary)g(T)-11 b(ables)0 3813 y Fj(CFITSIO)33 b(pro)m(vides)h(easy-to-use)i(supp)s (ort)d(for)i(reading)f(and)g(writing)f(data)i(in)f(v)-5 b(ariable)33 b(length)h(\014elds)g(of)h(a)0 3926 y(binary)f(table.)55 b(The)35 b(v)-5 b(ariable)34 b(length)g(columns)g(ha)m(v)m(e)j(TF)m (ORMn)e(k)m(eyw)m(ord)h(v)-5 b(alues)34 b(of)i(the)f(form)g (`1Pt\(len\)')0 4039 y(where)25 b(`t')i(is)d(the)i(data)g(t)m(yp)s(e)g (co)s(de)g(\(e.g.,)j(I,)c(J,)h(E,)f(D,)i(etc.\))40 b(and)25 b(`len')h(is)e(an)i(in)m(teger)g(sp)s(ecifying)d(the)j(maxim)m(um)0 4152 y(length)g(of)h(the)h(v)m(ector)g(in)e(the)h(table.)39 b(If)27 b(the)g(v)-5 b(alue)26 b(of)h(`len')g(is)f(not)h(sp)s (eci\014ed)e(when)h(the)h(table)g(is)f(created)i(\(e.g.,)0 4264 y(if)33 b(the)h(TF)m(ORM)h(k)m(eyw)m(ord)g(v)-5 b(alue)33 b(is)g(simply)f(sp)s(eci\014ed)h(as)h('1PE')h(instead)e(of)h ('1PE\(400\))j(\),)f(then)d(CFITSIO)0 4377 y(will)27 b(automatically)i(scan)g(the)h(table)f(when)g(it)g(is)f(closed)h(to)h (determine)f(the)g(maxim)m(um)f(length)h(of)h(the)f(v)m(ector)0 4490 y(and)h(will)d(app)s(end)i(this)g(v)-5 b(alue)30 b(to)h(the)g(TF)m(ORMn)f(v)-5 b(alue.)0 4650 y(The)29 b(same)h(routines)f(that)h(read)f(and)g(write)g(data)h(in)f(an)g (ordinary)f(\014xed)h(length)g(binary)f(table)h(extension)h(are)0 4763 y(also)40 b(used)e(for)i(v)-5 b(ariable)38 b(length)h(\014elds,)h (ho)m(w)m(ev)m(er,)k(the)c(routine)e(parameters)i(tak)m(e)h(on)f(a)g (sligh)m(tly)d(di\013eren)m(t)0 4876 y(in)m(terpretation)30 b(as)g(describ)s(ed)f(b)s(elo)m(w.)0 5036 y(All)35 b(the)h(data)h(in)e (a)i(v)-5 b(ariable)35 b(length)g(\014eld)g(is)g(written)h(in)m(to)g (an)g(area)h(called)f(the)g(`heap')g(whic)m(h)f(follo)m(ws)h(the)0 5149 y(main)30 b(\014xed-length)h(FITS)f(binary)g(table.)43 b(The)31 b(size)g(of)g(the)h(heap,)f(in)f(b)m(ytes,)i(is)f(sp)s (eci\014ed)e(b)m(y)i(the)h(PCOUNT)0 5262 y(k)m(eyw)m(ord)21 b(in)e(the)i(FITS)f(header.)37 b(When)20 b(creating)h(a)g(new)f(binary) f(table,)j(the)f(initial)d(v)-5 b(alue)20 b(of)g(PCOUNT)g(should)0 5375 y(usually)25 b(b)s(e)j(set)g(to)g(zero.)41 b(CFITSIO)26 b(will)f(recompute)j(the)g(size)f(of)h(the)g(heap)g(as)g(the)g(data)g (is)f(written)f(and)i(will)0 5488 y(automatically)d(up)s(date)f(the)i (PCOUNT)e(k)m(eyw)m(ord)h(v)-5 b(alue)25 b(when)f(the)h(table)g(is)f (closed.)39 b(When)25 b(writing)e(v)-5 b(ariable)0 5601 y(length)33 b(data)h(to)g(a)g(table,)h(CFITSIO)d(will)e(automatically)k (extend)f(the)h(size)f(of)h(the)g(heap)f(area)h(if)f(necessary)-8 b(,)0 5714 y(so)31 b(that)g(an)m(y)f(follo)m(wing)f(HDUs)i(do)f(not)h (get)h(o)m(v)m(erwritten.)p eop %%Page: 25 33 25 32 bop 0 299 a Fh(4.11.)73 b(MUL)-8 b(TIPLE)30 b(A)m(CCESS)f(TO)g (THE)i(SAME)f(FITS)f(FILE)1515 b Fj(25)0 555 y(By)30 b(default)e(the)i(heap)f(data)i(area)f(starts)g(immediately)e(after)i (the)f(last)h(ro)m(w)f(of)h(the)g(\014xed-length)e(table.)41 b(This)0 668 y(default)26 b(starting)g(lo)s(cation)h(ma)m(y)g(b)s(e)f (o)m(v)m(erridden)g(b)m(y)h(the)g(THEAP)f(k)m(eyw)m(ord,)i(but)f(this)e (is)h(not)h(recommended.)0 781 y(If)34 b(additional)e(ro)m(ws)i(of)g (data)h(are)g(added)e(to)i(the)f(table,)i(CFITSIO)c(will)g (automatically)i(shift)e(the)j(the)f(heap)0 894 y(do)m(wn)g(to)i(mak)m (e)f(ro)s(om)g(for)f(the)h(new)f(ro)m(ws,)i(but)e(it)h(is)e(ob)m (viously)h(b)s(e)g(more)h(e\016cien)m(t)g(to)g(initially)c(create)37 b(the)0 1007 y(table)30 b(with)e(the)i(necessary)g(n)m(um)m(b)s(er)f (of)h(blank)e(ro)m(ws,)i(so)g(that)g(the)g(heap)g(do)s(es)f(not)h (needed)g(to)g(b)s(e)f(constan)m(tly)0 1120 y(mo)m(v)m(ed.)0 1280 y(When)g(writing)f(to)i(a)g(v)-5 b(ariable)29 b(length)g(\014eld)f (the)i(en)m(tire)f(arra)m(y)h(of)g(v)-5 b(alues)29 b(for)h(a)g(giv)m (en)f(ro)m(w)h(of)g(the)g(table)f(m)m(ust)0 1393 y(b)s(e)e(written)f (with)h(a)h(single)e(call)g(to)j(\014ts)p 1363 1393 28 4 v 32 w(write)p 1598 1393 V 32 w(col.)40 b(The)27 b(total)h(length)f (of)h(the)g(arra)m(y)g(is)e(giv)m(en)i(b)m(y)f(nelemen)m(ts)g(+)0 1506 y(\014rstelem)33 b(-)g(1.)51 b(Additional)31 b(elemen)m(ts)j (cannot)g(b)s(e)f(app)s(ended)f(to)i(an)f(existing)g(v)m(ector)i(at)f (a)g(later)f(time)h(since)0 1619 y(an)m(y)c(attempt)g(to)g(do)f(so)g (will)e(simply)f(o)m(v)m(erwrite)k(all)e(the)i(previously)c(written)j (data.)41 b(Note)30 b(also)f(that)h(the)f(new)0 1732 y(data)c(will)d(b)s(e)i(written)g(to)h(a)g(new)f(area)i(of)f(the)f (heap)h(and)f(the)h(heap)f(space)h(used)f(b)m(y)h(the)f(previous)g (write)f(cannot)0 1844 y(b)s(e)32 b(reclaimed.)45 b(F)-8 b(or)34 b(this)d(reason)h(eac)m(h)i(ro)m(w)f(of)f(a)h(v)-5 b(ariable)31 b(length)h(\014eld)f(should)f(only)i(b)s(e)f(written)h (once.)47 b(An)0 1957 y(exception)37 b(to)g(this)f(general)g(rule)f(o)s (ccurs)i(when)e(setting)i(elemen)m(ts)g(of)g(an)f(arra)m(y)h(as)g (unde\014ned.)57 b(One)36 b(m)m(ust)0 2070 y(\014rst)30 b(write)g(a)i(dumm)m(y)d(v)-5 b(alue)31 b(in)m(to)g(the)g(arra)m(y)g (with)f(\014ts)p 1977 2070 V 32 w(write)p 2212 2070 V 32 w(col,)i(and)e(then)h(call)f(\014ts)p 3086 2070 V 32 w(write)p 3321 2070 V 32 w(col)p 3464 2070 V 33 w(n)m(ul)g(to)i (\015ag)0 2183 y(the)g(desired)e(elemen)m(ts)i(as)g(unde\014ned.)43 b(\(Do)33 b(not)f(use)g(the)g(\014ts)p 2197 2183 V 32 w(write)p 2432 2183 V 32 w(coln)m(ull)e(routines)g(with)h(v)-5 b(ariable)31 b(length)0 2296 y(\014elds\).)45 b(Note)33 b(that)g(the)f(ro)m(ws)h(of)f(a)g(table,)h(whether)f(\014xed)f(or)h(v) -5 b(ariable)31 b(length,)i(do)f(not)g(ha)m(v)m(e)h(to)g(b)s(e)f (written)0 2409 y(consecutiv)m(ely)f(and)e(ma)m(y)i(b)s(e)f(written)f (in)h(an)m(y)g(order.)0 2569 y(When)40 b(writing)f(to)i(a)g(v)-5 b(ariable)39 b(length)h(ASCI)s(I)f(c)m(haracter)j(\014eld)d(\(e.g.,)45 b(TF)m(ORM)c(=)f('1P)-8 b(A'\))43 b(only)c(a)i(single)0 2682 y(c)m(haracter)22 b(string)d(can)i(b)s(e)e(written.)37 b(The)20 b(`\014rstelem')f(and)h(`nelemen)m(ts')h(parameter)f(v)-5 b(alues)20 b(in)f(the)h(\014ts)p 3526 2682 V 33 w(write)p 3762 2682 V 32 w(col)0 2795 y(routine)34 b(are)i(ignored)e(and)g(the)i (n)m(um)m(b)s(er)d(of)j(c)m(haracters)g(to)g(write)e(is)h(simply)d (determined)i(b)m(y)h(the)g(length)g(of)0 2908 y(the)c(input)d(n)m (ull-terminated)g(c)m(haracter)k(string.)0 3068 y(The)21 b(\014ts)p 305 3068 V 33 w(write)p 541 3068 V 32 w(descript)f(routine)h (is)f(useful)g(in)g(situations)h(where)g(m)m(ultiple)e(ro)m(ws)j(of)g (a)g(v)-5 b(ariable)20 b(length)h(column)0 3181 y(ha)m(v)m(e)32 b(the)e(iden)m(tical)f(arra)m(y)i(of)g(v)-5 b(alues.)40 b(One)30 b(can)g(simply)e(write)i(the)g(arra)m(y)h(once)g(for)g(the)f (\014rst)g(ro)m(w,)g(and)g(then)0 3294 y(use)c(\014ts)p 280 3294 V 32 w(write)p 515 3294 V 32 w(descript)f(to)h(write)f(the)h (same)h(descriptor)d(v)-5 b(alues)26 b(in)m(to)g(the)g(other)g(ro)m (ws;)h(all)e(the)h(ro)m(ws)g(will)d(then)0 3407 y(p)s(oin)m(t)29 b(to)i(the)g(same)g(storage)h(lo)s(cation)e(th)m(us)g(sa)m(ving)g(disk) f(space.)0 3567 y(When)35 b(reading)f(from)g(a)i(v)-5 b(ariable)33 b(length)i(arra)m(y)g(\014eld)f(one)h(can)g(only)g(read)f (as)i(man)m(y)f(elemen)m(ts)g(as)g(actually)0 3680 y(exist)h(in)e(that) j(ro)m(w)e(of)h(the)g(table;)j(reading)c(do)s(es)h(not)g(automatically) f(con)m(tin)m(ue)h(with)f(the)h(next)g(ro)m(w)g(of)g(the)0 3793 y(table)28 b(as)g(o)s(ccurs)g(when)f(reading)g(an)h(ordinary)f (\014xed)g(length)g(table)h(\014eld.)39 b(A)m(ttempts)29 b(to)g(read)f(more)g(than)g(this)0 3906 y(will)h(cause)k(an)e(error)h (status)g(to)g(b)s(e)f(returned.)44 b(One)32 b(can)g(determine)f(the)h (n)m(um)m(b)s(er)e(of)i(elemen)m(ts)g(in)f(eac)m(h)i(ro)m(w)0 4019 y(of)e(a)f(v)-5 b(ariable)29 b(column)h(with)f(the)h(\014ts)p 1329 4019 V 33 w(read)p 1534 4019 V 32 w(descript)g(routine.)0 4432 y Ff(4.11)136 b(Multiple)45 b(Access)g(to)g(the)g(Same)h(FITS)d (File)0 4698 y Fj(CFITSIO)35 b(supp)s(orts)g(sim)m(ultaneous)g(read)h (and)g(write)g(access)h(to)h(m)m(ultiple)c(HDUs)j(in)e(the)i(same)g (FITS)f(\014le.)0 4811 y(Th)m(us,)43 b(one)e(can)h(op)s(en)e(the)h (same)h(FITS)e(\014le)g(t)m(wice)i(within)c(a)k(single)d(program)i(and) g(mo)m(v)m(e)h(to)g(2)f(di\013eren)m(t)0 4924 y(HDUs)30 b(in)e(the)i(\014le,)f(and)g(then)g(read)h(and)e(write)h(data)h(or)g(k) m(eyw)m(ords)g(to)g(the)g(2)f(extensions)h(just)e(as)i(if)f(one)g(w)m (ere)0 5036 y(accessing)e(2)g(completely)f(separate)h(FITS)f(\014les.) 38 b(Since)26 b(in)f(general)h(it)g(is)g(not)h(p)s(ossible)d(to)j(ph)m (ysically)d(op)s(en)i(the)0 5149 y(same)36 b(\014le)f(t)m(wice)h(and)f (then)g(exp)s(ect)h(to)g(b)s(e)f(able)g(to)i(sim)m(ultaneously)c(\(or)j (in)e(alternating)h(succession\))h(write)0 5262 y(to)f(2)f(di\013eren)m (t)g(lo)s(cations)g(in)e(the)j(\014le,)f(CFITSIO)f(recognizes)i(when)e (the)h(\014le)f(to)i(b)s(e)f(op)s(ened)f(\(in)g(the)i(call)e(to)0 5375 y(\014ts)p 127 5375 V 32 w(op)s(en)p 349 5375 V 33 w(\014le\))28 b(has)g(already)g(b)s(een)g(op)s(ened)g(and)g(instead) g(of)h(actually)f(op)s(ening)f(the)i(\014le)f(again,)h(just)f (logically)0 5488 y(links)g(the)j(new)f(\014le)g(to)h(the)g(old)e (\014le.)41 b(\(This)29 b(only)h(applies)e(if)i(the)h(\014le)e(is)h(op) s(ened)g(more)g(than)g(once)i(within)c(the)0 5601 y(same)g(program,)g (and)f(do)s(es)h(not)f(prev)m(en)m(t)i(the)f(same)g(\014le)e(from)h(b)s (eing)g(sim)m(ultaneously)e(op)s(ened)i(b)m(y)g(more)h(than)0 5714 y(one)h(program\).)40 b(Then)28 b(b)s(efore)g(CFITSIO)f(reads)h (or)h(writes)f(to)h(either)f(\(logical\))h(\014le,)f(it)g(mak)m(es)i (sure)d(that)j(an)m(y)p eop %%Page: 26 34 26 33 bop 0 299 a Fj(26)1763 b Fh(CHAPTER)29 b(4.)112 b(PR)m(OGRAMMING)32 b(GUIDELINES)0 555 y Fj(mo)s(di\014cations)e(made)h (to)h(the)g(other)g(\014le)e(ha)m(v)m(e)j(b)s(een)e(completely)g (\015ushed)e(from)i(the)h(in)m(ternal)e(bu\013ers)h(to)h(the)0 668 y(\014le.)43 b(Th)m(us,)30 b(in)g(principle,)f(one)i(could)f(op)s (en)h(a)h(\014le)e(t)m(wice,)i(in)e(one)i(case)g(p)s(oin)m(ting)e(to)i (the)f(\014rst)g(extension)g(and)0 781 y(in)i(the)i(other)g(p)s(oin)m (ting)d(to)k(the)e(2nd)g(extension)h(and)e(then)i(write)e(data)j(to)f (b)s(oth)f(extensions,)h(in)e(an)m(y)i(order,)0 894 y(without)24 b(danger)i(of)f(corrupting)g(the)g(\014le,)h(There)f(ma)m(y)h(b)s(e)f (some)h(e\016ciency)f(p)s(enalties)f(in)g(doing)h(this)f(ho)m(w)m(ev)m (er,)0 1007 y(since)j(CFITSIO)g(has)h(to)h(\015ush)d(all)h(the)h(in)m (ternal)f(bu\013ers)g(related)h(to)h(one)f(\014le)f(b)s(efore)h(switc)m (hing)e(to)j(the)f(other,)0 1120 y(so)i(it)g(w)m(ould)f(still)f(b)s(e)i (pruden)m(t)f(to)i(minimize)d(the)i(n)m(um)m(b)s(er)f(of)i(times)e(one) i(switc)m(hes)f(bac)m(k)h(and)e(forth)h(b)s(et)m(w)m(een)0 1233 y(doing)f(I/O)i(to)g(di\013eren)m(t)f(HDUs)h(in)e(the)h(same)h (\014le.)0 1571 y Ff(4.12)136 b(When)44 b(the)h(Final)h(Size)f(of)g (the)g(FITS)f(HDU)h(is)g(Unkno)l(wn)0 1822 y Fj(It)27 b(is)g(not)g(required)e(to)j(kno)m(w)f(the)h(total)g(size)f(of)g(a)h (FITS)e(data)i(arra)m(y)g(or)f(table)g(b)s(efore)g(b)s(eginning)d(to)k (write)f(the)0 1935 y(data)32 b(to)f(the)g(FITS)f(\014le.)42 b(In)30 b(the)h(case)h(of)f(the)g(primary)e(arra)m(y)i(or)g(an)f(image) i(extension,)e(one)i(should)c(initially)0 2047 y(create)j(the)e(arra)m (y)h(with)d(the)j(size)f(of)g(the)g(highest)f(dimension)f(\(largest)j (NAXISn)e(k)m(eyw)m(ord\))i(set)g(to)g(a)f(dumm)m(y)0 2160 y(v)-5 b(alue,)25 b(suc)m(h)f(as)g(1.)39 b(Then)23 b(after)i(all)e(the)i(data)f(ha)m(v)m(e)i(b)s(een)d(written)g(and)h (the)g(true)g(dimensions)e(are)i(kno)m(wn,)h(then)0 2273 y(the)33 b(NAXISn)f(v)-5 b(alue)32 b(should)f(b)s(e)h(up)s(dated)g (using)f(the)i(\014ts)p 2069 2273 28 4 v 33 w(up)s(date)p 2378 2273 V 32 w(k)m(ey)g(routine)f(b)s(efore)h(mo)m(ving)f(to)i (another)0 2386 y(extension)c(or)g(closing)g(the)g(FITS)g(\014le.)0 2546 y(When)f(writing)e(to)i(FITS)g(tables,)g(CFITSIO)e(automatically)i (k)m(eeps)h(trac)m(k)g(of)f(the)g(highest)g(ro)m(w)g(n)m(um)m(b)s(er)e (that)0 2659 y(is)k(written)g(to,)i(and)e(will)e(increase)j(the)g(size) g(of)g(the)g(table)f(if)g(necessary)-8 b(.)46 b(CFITSIO)30 b(will)f(also)j(automatically)0 2772 y(insert)j(space)i(in)e(the)h (FITS)f(\014le)h(if)f(necessary)-8 b(,)39 b(to)e(ensure)e(that)i(the)f (data)h('heap',)h(if)d(it)h(exists,)h(and/or)g(an)m(y)0 2885 y(additional)26 b(HDUs)j(that)g(follo)m(w)e(the)i(table)f(do)g (not)h(get)g(o)m(v)m(erwritten)g(as)f(new)g(ro)m(ws)g(are)h(written)e (to)i(the)g(table.)0 3045 y(As)37 b(a)h(general)f(rule)f(it)h(is)f(b)s (est)h(to)h(sp)s(ecify)e(the)i(initial)c(n)m(um)m(b)s(er)i(of)i(ro)m (ws)f(=)g(0)g(when)g(the)g(table)g(is)g(created,)0 3158 y(then)h(let)g(CFITSIO)f(k)m(eep)i(trac)m(k)g(of)g(the)f(n)m(um)m(b)s (er)f(of)i(ro)m(ws)f(that)h(are)f(actually)g(written.)64 b(The)38 b(application)0 3271 y(program)e(should)e(not)j(man)m(ually)e (up)s(date)g(the)i(n)m(um)m(b)s(er)e(of)h(ro)m(ws)g(in)f(the)i(table)f (\(as)h(giv)m(en)f(b)m(y)g(the)h(NAXIS2)0 3384 y(k)m(eyw)m(ord\))j (since)e(CFITSIO)f(do)s(es)i(this)f(automatically)-8 b(.)66 b(If)38 b(a)i(table)e(is)g(initially)e(created)k(with)d(more)i (than)0 3497 y(zero)i(ro)m(ws,)j(then)c(this)g(will)d(usually)i(b)s(e)h (considered)f(as)i(the)g(minim)m(um)d(size)i(of)h(the)g(table,)i(ev)m (en)e(if)f(few)m(er)0 3610 y(ro)m(ws)30 b(are)g(actually)f(written)g (to)i(the)f(table.)40 b(Th)m(us,)30 b(if)e(a)j(table)e(is)g(initially)d (created)31 b(with)e(NAXIS2)h(=)f(20,)j(and)0 3723 y(CFITSIO)f(only)h (writes)f(10)j(ro)m(ws)e(of)h(data)g(b)s(efore)f(closing)g(the)h (table,)g(then)f(NAXIS2)h(will)d(remain)h(equal)h(to)0 3836 y(20.)50 b(If)33 b(ho)m(w)m(ev)m(er,)i(30)g(ro)m(ws)e(of)g(data)h (are)g(written)e(to)i(this)e(table,)i(then)f(NAXIS2)h(will)c(b)s(e)j (increased)f(from)h(20)0 3949 y(to)f(30.)44 b(The)31 b(one)g(exception)h(to)g(this)e(automatic)i(up)s(dating)d(of)i(the)h (NAXIS2)f(k)m(eyw)m(ord)h(is)e(if)g(the)i(application)0 4061 y(program)c(directly)e(mo)s(di\014es)g(the)j(v)-5 b(alue)27 b(of)h(NAXIS2)g(\(up)f(or)h(do)m(wn\))g(itself)f(just)g(b)s (efore)h(closing)f(the)h(table.)40 b(In)0 4174 y(this)27 b(case,)j(CFITSIO)d(do)s(es)h(not)h(up)s(date)e(NAXIS2)i(again,)g (since)f(it)g(assumes)g(that)h(the)f(application)f(program)0 4287 y(m)m(ust)32 b(ha)m(v)m(e)h(had)f(a)g(go)s(o)s(d)g(reason)h(for)f (c)m(hanging)g(the)g(v)-5 b(alue)32 b(directly)-8 b(.)45 b(This)30 b(is)h(not)i(recommended,)f(ho)m(w)m(ev)m(er,)0 4400 y(and)j(is)g(only)g(pro)m(vided)g(for)g(bac)m(kw)m(ard)h (compatibilit)m(y)e(with)h(soft)m(w)m(are)i(that)g(initially)32 b(creates)37 b(a)f(table)g(with)0 4513 y(a)e(large)g(n)m(um)m(b)s(er)f (of)h(ro)m(ws,)h(than)f(decreases)g(the)h(NAXIS2)f(v)-5 b(alue)33 b(to)i(the)f(actual)g(smaller)f(v)-5 b(alue)33 b(just)g(b)s(efore)0 4626 y(closing)c(the)i(table.)0 4964 y Ff(4.13)136 b(CFITSIO)44 b(Size)h(Limitations)0 5215 y Fj(CFITSIO)29 b(places)i(v)m(ery)g(few)g(restrictions)e(on)i (the)g(size)f(of)h(FITS)f(\014les)g(that)h(it)g(reads)f(or)h(writes.)41 b(There)30 b(are)i(a)0 5328 y(few)e(limits,)e(ho)m(w)m(ev)m(er,)k(that) f(ma)m(y)g(a\013ect)h(some)f(extreme)g(cases:)0 5488 y(1.)43 b(The)31 b(maxim)m(um)f(n)m(um)m(b)s(er)g(of)h(FITS)f(\014les)g (that)i(ma)m(y)g(b)s(e)e(sim)m(ultaneously)f(op)s(ened)i(b)m(y)g (CFITSIO)e(is)h(set)i(b)m(y)0 5601 y(NMAXFILES)i(as)g(de\014ned)f(in)g (\014tsio2.h.)51 b(It)34 b(is)f(curren)m(tly)g(set)i(=)f(300)h(b)m(y)f (default.)51 b(CFITSIO)32 b(will)f(allo)s(cate)0 5714 y(ab)s(out)i(80)g(*)h(NMAXFILES)f(b)m(ytes)g(of)g(memory)g(for)g(in)m (ternal)e(use.)48 b(Note)34 b(that)g(the)f(underlying)d(C)i(compiler)p eop %%Page: 27 35 27 34 bop 0 299 a Fh(4.13.)73 b(CFITSIO)28 b(SIZE)h(LIMIT)-8 b(A)g(TIONS)2300 b Fj(27)0 555 y(or)39 b(op)s(erating)g(system,)k(ma)m (y)d(ha)m(v)m(e)g(a)g(smaller)e(limit)g(on)h(the)h(n)m(um)m(b)s(er)e (of)i(op)s(ened)e(\014les.)67 b(The)39 b(C)h(sym)m(b)s(olic)0 668 y(constan)m(t)31 b(F)m(OPEN)p 690 668 28 4 v 34 w(MAX)f(is)f(in)m (tended)g(to)i(de\014ne)e(the)i(maxim)m(um)e(n)m(um)m(b)s(er)f(of)j (\014les)e(that)h(ma)m(y)h(op)s(en)e(at)i(once)0 781 y(\(including)d(an)m(y)j(other)g(text)h(or)f(binary)e(\014les)h(that)i (ma)m(y)f(b)s(e)g(op)s(en,)f(not)h(just)g(FITS)f(\014les\).)42 b(On)30 b(some)h(systems)0 894 y(it)f(has)g(b)s(een)g(found)f(that)i (gcc)g(supp)s(orts)e(a)h(maxim)m(um)g(of)g(255)i(op)s(ened)e(\014les.)0 1054 y(Note)d(that)e(op)s(ening)f(and)h(op)s(erating)g(on)g(man)m(y)g (FITS)g(\014les)f(sim)m(ultaneously)f(in)h(parallel)f(ma)m(y)j(b)s(e)f (less)f(e\016cien)m(t)0 1167 y(than)k(op)s(erating)g(on)g(smaller)f (groups)h(of)h(\014les)e(in)g(series.)40 b(CFITSIO)27 b(only)g(has)h(NIOBUF)h(n)m(um)m(b)s(er)f(of)g(in)m(ternal)0 1280 y(bu\013ers)j(\(set)j(=)e(40)i(b)m(y)e(default\))h(that)g(are)g (used)f(for)g(temp)s(orary)g(storage)i(of)f(the)g(most)g(recen)m(t)h (data)f(records)0 1393 y(that)40 b(ha)m(v)m(e)g(b)s(een)e(read)h(or)g (written)f(in)f(the)i(FITS)f(\014les.)66 b(If)38 b(the)h(n)m(um)m(b)s (er)f(of)h(op)s(ened)f(\014les)g(is)g(greater)i(than)0 1506 y(NIOBUF,)j(then)f(CFITSIO)e(ma)m(y)j(w)m(aste)h(more)e(time)g (\015ushing)d(and)j(re-reading)g(or)g(re-writing)e(the)j(same)0 1619 y(records)30 b(in)f(the)i(FITS)e(\014les.)0 1779 y(2.)54 b(By)35 b(default,)g(CFITSIO)e(can)i(handle)f(FITS)g(\014les)f (up)h(to)h(2.1)h(GB)g(in)d(size)i(\(2**31)i(b)m(ytes\).)54 b(This)33 b(\014le)h(size)0 1892 y(limit)k(is)i(often)g(imp)s(osed)f(b) m(y)h(32-bit)h(op)s(erating)e(systems.)71 b(More)41 b(recen)m(tly)-8 b(,)44 b(as)d(64-bit)f(op)s(erating)g(systems)0 2005 y(b)s(ecome)33 b(more)g(common,)g(an)g(industry-wide)c(standard)j(\(at) i(least)e(on)h(Unix)e(systems\))i(has)g(b)s(een)f(dev)m(elop)s(ed)0 2118 y(to)39 b(supp)s(ort)d(larger)h(sized)h(\014les)f(\(see)h(h)m (ttp://ftp.sas.com/standards/large.\014le/\).)66 b(Starting)38 b(with)e(v)m(ersion)0 2230 y(2.1)45 b(of)e(CFITSIO,)f(larger)h(FITS)g (\014les)f(up)h(to)h(6)g(terab)m(ytes)h(in)d(size)h(ma)m(y)h(b)s(e)f (read)g(and)g(written)g(on)g(sup-)0 2343 y(p)s(orted)f(platforms.)75 b(In)42 b(order)g(to)h(supp)s(ort)e(these)h(larger)g(\014les,)j (CFITSIO)c(m)m(ust)h(b)s(e)g(compiled)f(with)g(the)0 2456 y('-D)p 129 2456 V 34 w(LAR)m(GEFILE)p 696 2456 V 33 w(SOUR)m(CE')h(and)g(`-D)p 1491 2456 V 34 w(FILE)p 1736 2456 V 33 w(OFFSET)p 2137 2456 V 32 w(BITS=64')h(compiler)e (\015ags.)78 b(Some)43 b(platforms)0 2569 y(ma)m(y)c(also)f(require)f (the)h(`-D)p 1002 2569 V 34 w(LAR)m(GE)p 1358 2569 V 33 w(FILES')g(compiler)f(\015ag.)64 b(This)37 b(causes)h(the)h (compiler)e(to)i(allo)s(cate)f(8-)0 2682 y(b)m(ytes)27 b(instead)f(of)h(4-b)m(ytes)h(for)f(the)g(`o\013)p 1371 2682 V 33 w(t')g(data)h(t)m(yp)s(e)f(that)g(is)f(used)g(to)h(store)h (\014le)e(o\013set)h(p)s(ositions.)38 b(It)27 b(app)s(ears)0 2795 y(that)i(in)d(most)j(cases)g(it)e(is)g(not)h(necessary)h(to)g (also)f(include)d(these)k(compiler)d(\015ags)j(when)e(compiling)e (programs)0 2908 y(that)31 b(link)d(to)j(the)g(CFITSIO)e(library)-8 b(.)0 3068 y(If)21 b(CFITSIO)e(is)h(compiled)g(with)g(the)h(-D)p 1386 3068 V 33 w(LAR)m(GEFILE)p 1952 3068 V 34 w(SOUR)m(CE)f(and)g(-D)p 2654 3068 V 34 w(FILE)p 2899 3068 V 33 w(OFFSET)p 3300 3068 V 32 w(BITS=64)h(\015ags)0 3181 y(on)36 b(a)g(platform)f(that)h (supp)s(orts)e(large)i(\014les,)h(then)e(it)h(can)g(read)g(and)f(write) g(FITS)g(\014les)g(that)h(con)m(tain)g(up)f(to)0 3294 y(2**31)k(2880-b)m(yte)g(FITS)d(records,)j(or)d(appro)m(ximately)g(6)h (terab)m(ytes)h(in)e(size.)59 b(It)37 b(is)f(still)f(required)f(that)k (the)0 3407 y(v)-5 b(alue)29 b(of)g(the)g(NAXISn)f(and)h(PCOUNT)f(k)m (eyw)m(ords)h(in)f(eac)m(h)i(extension)f(b)s(e)f(within)f(the)i(range)h (of)f(a)g(signed)f(4-)0 3520 y(b)m(yte)d(in)m(teger)g(\(max)g(v)-5 b(alue)25 b(=)f(2,147,483,648\).)44 b(Th)m(us,)25 b(eac)m(h)h (dimension)c(of)j(an)f(image)h(\(giv)m(en)g(b)m(y)g(the)g(NAXISn)0 3633 y(k)m(eyw)m(ords\),)32 b(the)f(total)h(width)d(of)i(a)g(table)g (\(NAXIS1)h(k)m(eyw)m(ord\),)g(the)f(n)m(um)m(b)s(er)f(of)h(ro)m(ws)g (in)e(a)i(table)g(\(NAXIS2)0 3745 y(k)m(eyw)m(ord\),)d(and)d(the)h (total)h(size)f(of)g(the)g(v)-5 b(ariable-length)25 b(arra)m(y)h(heap)g (in)f(binary)f(tables)i(\(PCOUNT)f(k)m(eyw)m(ord\))0 3858 y(m)m(ust)30 b(b)s(e)g(less)g(than)g(this)f(limit.)0 4019 y(Curren)m(tly)-8 b(,)30 b(supp)s(ort)f(for)i(large)g(\014les)f (within)e(CFITSIO)h(has)i(b)s(een)f(tested)i(on)f(the)g(Lin)m(ux,)f (Solaris,)f(and)h(IBM)0 4131 y(AIX)g(op)s(erating)g(systems.)p eop %%Page: 28 36 28 35 bop 0 299 a Fj(28)1763 b Fh(CHAPTER)29 b(4.)112 b(PR)m(OGRAMMING)32 b(GUIDELINES)p eop %%Page: 29 37 29 36 bop 0 1225 a Fg(Chapter)65 b(5)0 1687 y Fm(Basic)77 b(CFITSIO)f(In)-6 b(terface)77 b(Routines)0 2180 y Fj(This)29 b(c)m(hapter)j(describ)s(es)d(the)j(basic)e(routines)g(in)g(the)h (CFITSIO)e(user)i(in)m(terface)g(that)h(pro)m(vide)e(all)g(the)i(func-) 0 2293 y(tions)i(normally)f(needed)i(to)g(read)g(and)f(write)g(most)i (FITS)e(\014les.)53 b(It)35 b(is)f(recommended)g(that)i(these)f (routines)0 2406 y(b)s(e)d(used)g(for)g(most)h(applications)e(and)h (that)h(the)f(more)h(adv)-5 b(anced)33 b(routines)e(describ)s(ed)g(in)g (the)i(next)f(c)m(hapter)0 2518 y(only)d(b)s(e)h(used)g(in)f(sp)s (ecial)g(circumstances)h(when)f(necessary)-8 b(.)0 2679 y(The)30 b(follo)m(wing)f(con)m(v)m(en)m(tions)i(are)g(used)e(in)h (this)f(c)m(hapter)i(in)e(the)h(description)f(of)h(eac)m(h)i(function:) 0 2839 y(1.)39 b(Most)25 b(functions)d(ha)m(v)m(e)j(2)f(names:)37 b(a)24 b(long)g(descriptiv)m(e)e(name)i(and)f(a)i(short)e(concise)h (name.)38 b(Both)25 b(names)f(are)0 2952 y(listed)e(on)h(the)g(\014rst) f(line)g(of)h(the)h(follo)m(wing)d(descriptions,)i(separated)g(b)m(y)h (a)f(slash)f(\(/\))i(c)m(haracter.)40 b(Programmers)0 3065 y(ma)m(y)27 b(use)g(either)f(name)h(in)e(their)h(programs)h(but)f (the)h(long)f(names)h(are)g(recommended)f(to)i(help)d(do)s(cumen)m(t)i (the)0 3177 y(co)s(de)k(and)e(mak)m(e)j(it)e(easier)g(to)h(read.)0 3338 y(2.)42 b(A)30 b(righ)m(t)g(arro)m(w)h(sym)m(b)s(ol)e(\()p Fb(>)p Fj(\))i(is)f(used)g(in)f(the)i(function)e(descriptions)f(to)k (separate)f(the)g(input)e(parameters)0 3451 y(from)k(the)g(output)f (parameters)i(in)e(the)h(de\014nition)e(of)i(eac)m(h)h(routine.)48 b(This)31 b(sym)m(b)s(ol)h(is)g(not)h(actually)g(part)g(of)0 3563 y(the)e(C)f(calling)e(sequence.)0 3724 y(3.)41 b(The)30 b(function)f(parameters)i(are)g(de\014ned)e(in)g(more)h(detail)g(in)f (the)h(alphab)s(etical)f(listing)f(in)h(App)s(endix)f(B.)0 3884 y(4.)39 b(The)23 b(\014rst)g(argumen)m(t)g(in)g(almost)g(all)g (the)g(functions)f(is)h(a)h(p)s(oin)m(ter)e(to)i(a)g(structure)f(of)h (t)m(yp)s(e)g(`\014ts\014le'.)37 b(Memory)0 3997 y(for)26 b(this)f(structure)g(is)g(allo)s(cated)h(b)m(y)g(CFITSIO)e(when)h(the)h (FITS)g(\014le)f(is)g(\014rst)g(op)s(ened)g(or)h(created)h(and)e(is)g (freed)0 4110 y(when)k(the)i(FITS)f(\014le)f(is)g(closed.)0 4270 y(5.)53 b(The)34 b(last)g(argumen)m(t)g(in)f(almost)i(all)e(the)h (functions)f(is)g(the)i(error)f(status)g(parameter.)53 b(It)35 b(m)m(ust)f(b)s(e)f(equal)0 4383 y(to)k(0)g(on)f(input,)g (otherwise)g(the)g(function)f(will)f(immediately)g(exit)i(without)g (doing)f(an)m(ything.)58 b(A)36 b(non-zero)0 4496 y(output)27 b(v)-5 b(alue)26 b(indicates)h(that)g(an)g(error)g(o)s(ccurred)g(in)f (the)h(function.)38 b(In)27 b(most)g(cases)h(the)g(status)f(v)-5 b(alue)27 b(is)f(also)0 4608 y(returned)j(as)i(the)f(v)-5 b(alue)30 b(of)h(the)f(function)f(itself.)0 4935 y Ff(5.1)135 b(CFITSIO)44 b(Error)h(Status)h(Routines)0 5168 y Fi(1)81 b Fj(Return)27 b(a)j(descriptiv)m(e)d(text)j(string)d(\(30)j(c)m(har)f (max.\))41 b(corresp)s(onding)27 b(to)i(a)g(CFITSIO)e(error)h(status)h (co)s(de.)95 5385 y Fe(void)47 b(fits_get_errstatus)c(/)k(ffgerr)f (\(int)h(status,)f(>)h(char)g(*err_text\))0 5601 y Fi(2)81 b Fj(Return)35 b(the)h(top)g(\(oldest\))g(80-c)m(haracter)j(error)c (message)i(from)e(the)h(in)m(ternal)f(CFITSIO)f(stac)m(k)j(of)f(error) 227 5714 y(messages)45 b(and)e(shift)g(an)m(y)h(remaining)e(messages)j (on)f(the)g(stac)m(k)h(up)e(one)h(lev)m(el.)81 b(Call)42 b(this)h(routine)1905 5942 y(29)p eop %%Page: 30 38 30 37 bop 0 299 a Fj(30)1379 b Fh(CHAPTER)30 b(5.)71 b(BASIC)30 b(CFITSIO)f(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)227 555 y Fj(rep)s(eatedly)25 b(to)i(get)g(eac)m(h)g(message)f(in)f (sequence.)39 b(The)26 b(function)e(returns)h(a)h(v)-5 b(alue)25 b(=)g(0)h(and)g(a)g(n)m(ull)d(error)227 668 y(message)32 b(when)d(the)i(error)f(stac)m(k)i(is)d(empt)m(y)-8 b(.)95 923 y Fe(int)47 b(fits_read_errmsg)d(/)j(ffgmsg)f(\(char)h (*err_msg\))0 1178 y Fi(3)81 b Fj(Prin)m(t)29 b(out)i(the)g(error)f (message)i(corresp)s(onding)d(to)i(the)g(input)e(status)i(v)-5 b(alue)30 b(and)g(all)g(the)h(error)f(messages)227 1291 y(on)d(the)h(CFITSIO)e(stac)m(k)j(to)f(the)f(sp)s(eci\014ed)f(\014le)g (stream)i(\(normally)e(to)i(stdout)f(or)g(stderr\).)40 b(If)26 b(the)i(input)227 1404 y(status)j(v)-5 b(alue)30 b(=)g(0)h(then)f(this)f(routine)g(do)s(es)h(nothing.)95 1659 y Fe(void)47 b(fits_report_error)c(/)48 b(ffrprt)e(\(FILE)g (*stream,)g(>)h(status\))0 1914 y Fi(4)81 b Fj(The)44 b(\014ts)p 461 1914 28 4 v 32 w(write)p 696 1914 V 32 w(errmark)g(routine)g(puts)g(an)h(in)m(visible)c(mark)m(er)k(on)g(the)g (CFITSIO)e(error)h(stac)m(k.)85 b(The)227 2027 y(\014ts)p 354 2027 V 33 w(clear)p 574 2027 V 33 w(errmark)31 b(routine)h(can)h (then)f(b)s(e)f(used)h(to)h(delete)g(an)m(y)g(more)f(recen)m(t)i(error) e(messages)h(on)g(the)227 2140 y(stac)m(k,)42 b(bac)m(k)c(to)g(the)g(p) s(osition)e(of)i(the)g(mark)m(er.)63 b(This)36 b(preserv)m(es)h(an)m(y) h(older)f(error)g(messages)i(on)f(the)227 2253 y(stac)m(k.)77 b(The)41 b(\014ts)p 855 2253 V 32 w(clear)p 1074 2253 V 33 w(errmsg)g(routine)g(simply)e(clears)j(all)f(the)h(messages)g (\(and)g(marks\))f(from)h(the)227 2365 y(stac)m(k.)g(These)31 b(routines)e(are)i(called)e(without)h(an)m(y)g(argumen)m(ts.)95 2620 y Fe(void)47 b(fits_write_errmark)c(/)k(ffpmrk)f(\(void\))95 2733 y(void)h(fits_clear_errmark)c(/)k(ffcmrk)f(\(void\))95 2846 y(void)h(fits_clear_errmsg)c(/)48 b(ffcmsg)e(\(void\))0 3179 y Ff(5.2)135 b(FITS)44 b(File)i(Access)e(Routines)0 3419 y Fi(1)81 b Fj(Op)s(en)29 b(an)h(existing)f(data)i(\014le.)227 3663 y Fe(int)47 b(fits_open_file)d(/)k(ffopen)418 3776 y(\(fitsfile)d(**fptr,)h(char)h(*filename,)e(int)i(iomode,)f(>)h(int)g (*status\))227 4002 y(int)g(fits_open_diskfile)c(/)k(ffdkopen)418 4115 y(\(fitsfile)e(**fptr,)h(char)h(*filename,)e(int)i(iomode,)f(>)h (int)g(*status\))227 4340 y(int)g(fits_open_data)d(/)k(ffdopn)418 4453 y(\(fitsfile)d(**fptr,)h(char)h(*filename,)e(int)i(iomode,)f(>)h (int)g(*status\))227 4679 y(int)g(fits_open_table)d(/)j(fftopn)418 4792 y(\(fitsfile)e(**fptr,)h(char)h(*filename,)e(int)i(iomode,)f(>)h (int)g(*status\))227 5018 y(int)g(fits_open_image)d(/)j(ffiopn)418 5131 y(\(fitsfile)e(**fptr,)h(char)h(*filename,)e(int)i(iomode,)f(>)h (int)g(*status\))227 5375 y Fj(The)41 b(iomo)s(de)g(parameter)h (determines)f(the)g(read/write)g(access)i(allo)m(w)m(ed)f(in)e(the)h (\014le)g(and)g(can)h(ha)m(v)m(e)227 5488 y(v)-5 b(alues)31 b(of)h(READONL)-8 b(Y)32 b(\(0\))g(or)g(READ)m(WRITE)g(\(1\).)44 b(The)31 b(\014lename)g(parameter)h(giv)m(es)g(the)f(name)h(of)227 5601 y(the)f(\014le)f(to)h(b)s(e)f(op)s(ened,)h(follo)m(w)m(ed)f(b)m(y) h(an)f(optional)g(argumen)m(t)h(giving)f(the)h(name)f(or)h(index)e(n)m (um)m(b)s(er)h(of)227 5714 y(the)d(extension)f(within)f(the)h(FITS)g (\014le)g(that)h(should)e(b)s(e)h(mo)m(v)m(ed)i(to)f(and)f(op)s(ened)g (\(e.g.,)k Fe(myfile.fits+3)p eop %%Page: 31 39 31 38 bop 0 299 a Fh(5.2.)72 b(FITS)30 b(FILE)g(A)m(CCESS)f(R)m (OUTINES)2244 b Fj(31)227 555 y(or)36 b Fe(myfile.fits[3])d Fj(mo)m(v)m(es)k(to)g(the)g(3rd)f(extension)f(within)f(the)j(\014le,)g (and)e Fe(myfile.fits[events])227 668 y Fj(mo)m(v)m(es)d(to)f(the)g (extension)f(with)f(the)h(k)m(eyw)m(ord)h(EXTNAME)g(=)f('EVENTS'\).)227 816 y(The)37 b(\014ts)p 548 816 28 4 v 32 w(op)s(en)p 770 816 V 32 w(disk\014le)e(routine)h(is)g(similar)e(to)k(the)f(\014ts) p 2241 816 V 33 w(op)s(en)p 2464 816 V 32 w(\014le)f(routine)g(except)i (that)f(it)g(do)s(es)g(not)227 929 y(supp)s(ort)22 b(the)h(extended)h (\014lename)e(syn)m(tax)i(in)e(the)i(input)d(\014le)i(name.)38 b(This)22 b(routine)g(simply)f(tries)i(to)h(op)s(en)227 1042 y(the)36 b(sp)s(eci\014ed)d(input)h(\014le)g(on)h(magnetic)h (disk.)54 b(This)33 b(routine)h(is)h(mainly)e(for)i(use)g(in)f(cases)i (where)f(the)227 1155 y(\014lename)e(\(or)i(directory)e(path\))h(con)m (tains)g(square)g(or)g(curly)e(brac)m(k)m(et)k(c)m(haracters)f(that)f (w)m(ould)f(confuse)227 1268 y(the)e(extended)f(\014lename)g(parser.) 227 1416 y(The)j(\014ts)p 544 1416 V 32 w(op)s(en)p 766 1416 V 32 w(data)h(routine)d(is)h(similar)e(to)k(the)f(\014ts)p 2113 1416 V 32 w(op)s(en)p 2335 1416 V 33 w(\014le)e(routine)h(except)i (that)f(it)g(will)d(mo)m(v)m(e)k(to)227 1529 y(the)23 b(\014rst)f(HDU)h(con)m(taining)f(signi\014can)m(t)f(data,)k(if)d(a)h (HDU)g(name)f(or)h(n)m(um)m(b)s(er)e(to)i(op)s(en)f(w)m(as)h(not)f (explicitly)227 1642 y(sp)s(eci\014ed)36 b(as)h(part)h(of)f(the)h (\014lename.)60 b(In)37 b(this)f(case,)k(it)d(will)e(lo)s(ok)i(for)g (the)g(\014rst)g(IMA)m(GE)h(HDU)g(with)227 1755 y(NAXIS)e(>)f(0,)j(or)d (the)h(\014rst)f(table)g(that)i(do)s(es)e(not)h(con)m(tain)g(the)g (strings)e(`GTI')i(\(Go)s(o)s(d)g(Time)e(In)m(terv)-5 b(al)227 1868 y(extension\))31 b(or)f(`OBST)-8 b(ABLE')31 b(in)e(the)h(EXTNAME)h(k)m(eyw)m(ord)g(v)-5 b(alue.)227 2016 y(The)25 b(\014ts)p 536 2016 V 32 w(op)s(en)p 758 2016 V 32 w(table)g(and)f(\014ts)p 1305 2016 V 33 w(op)s(en)p 1528 2016 V 32 w(image)h(routines)f(are)h(similar)e(to)i(\014ts)p 2828 2016 V 33 w(op)s(en)p 3051 2016 V 32 w(data)h(except)f(they)h (will)227 2129 y(mo)m(v)m(e)h(to)g(the)f(\014rst)f(signi\014can)m(t)f (table)i(HDU)g(or)g(image)g(HDU)g(in)e(the)i(\014le,)g(resp)s(ectiv)m (ely)-8 b(,)27 b(if)d(a)i(HDU)h(name)227 2242 y(or)k(n)m(um)m(b)s(er)e (is)g(not)i(sp)s(eci\014ed)d(as)j(part)f(of)h(the)f(\014lename.)227 2390 y(IRAF)c(images)f(\(.imh)g(format)h(\014les\))e(and)h(ra)m(w)h (binary)d(data)k(arra)m(ys)e(ma)m(y)h(also)g(b)s(e)f(op)s(ened)f(with)g (READ-)227 2503 y(ONL)-8 b(Y)37 b(access.)60 b(CFITSIO)35 b(will)f(automatically)i(test)i(if)d(the)i(input)d(\014le)i(is)f(an)i (IRAF)f(image,)j(and)d(if,)227 2616 y(so)c(will)d(con)m(v)m(ert)k(it)e (on)g(the)h(\015y)f(in)m(to)h(a)g(virtual)d(FITS)i(image)h(b)s(efore)f (it)g(is)g(op)s(ened)f(b)m(y)i(the)g(application)227 2729 y(program.)64 b(If)37 b(the)h(input)f(\014le)g(is)g(a)h(ra)m(w)g (binary)f(data)h(arra)m(y)h(of)f(n)m(um)m(b)s(ers,)h(then)e(the)i(data) f(t)m(yp)s(e)h(and)227 2842 y(dimensions)34 b(of)i(the)g(arra)m(y)h(m)m (ust)f(b)s(e)f(sp)s(eci\014ed)f(in)h(square)h(brac)m(k)m(ets)h(follo)m (wing)e(the)h(name)g(of)h(the)f(\014le)227 2955 y(\(e.g.)56 b('ra)m(w\014le.dat[i512,512]')38 b(op)s(ens)c(a)i(512)g(x)f(512)h (short)e(in)m(teger)i(image\).)55 b(See)35 b(the)g(`Extended)g(File)227 3068 y(Name)k(Syn)m(tax')g(c)m(hapter)g(for)e(more)i(details)e(on)h(ho) m(w)g(to)h(sp)s(ecify)e(the)h(ra)m(w)h(\014le)e(name.)64 b(The)38 b(ra)m(w)g(\014le)227 3181 y(is)j(con)m(v)m(erted)h(on)f(the)h (\015y)f(in)m(to)g(a)g(virtual)f(FITS)g(image)i(in)e(memory)h(that)h (is)e(then)h(op)s(ened)g(b)m(y)g(the)227 3294 y(application)29 b(program)h(with)f(READONL)-8 b(Y)31 b(access.)227 3442 y(Programs)g(can)g(read)f(the)h(input)d(\014le)i(from)g(the)h('stdin')e (\014le)h(stream)h(if)e(a)i(dash)f(c)m(haracter)i(\('-'\))g(is)e(giv)m (en)227 3555 y(as)f(the)f(\014lename.)39 b(Files)28 b(can)g(also)g(b)s (e)g(op)s(ened)f(o)m(v)m(er)j(the)e(net)m(w)m(ork)h(using)e(FTP)h(or)g (HTTP)g(proto)s(cols)g(b)m(y)227 3668 y(supplying)f(the)k(appropriate)e (URL)i(as)f(the)h(\014lename.)227 3816 y(The)43 b(input)e(\014le)h(can) i(b)s(e)f(mo)s(di\014ed)e(in)g(v)-5 b(arious)43 b(w)m(a)m(ys)h(to)g (create)g(a)g(virtual)d(\014le)i(\(usually)e(stored)i(in)227 3929 y(memory\))31 b(that)g(is)f(then)g(op)s(ened)f(b)m(y)i(the)f (application)f(program)h(b)m(y)h(supplying)c(a)k(\014ltering)e(or)h (binning)227 4042 y(sp)s(eci\014er)d(in)g(square)h(brac)m(k)m(ets)h (follo)m(wing)e(the)h(\014lename.)39 b(Some)29 b(of)f(the)g(more)h (common)f(\014ltering)f(meth-)227 4155 y(o)s(ds)32 b(are)h(illustrated) e(in)g(the)i(follo)m(wing)f(paragraphs,)h(but)f(users)g(should)e(refer) j(to)g(the)g('Extended)g(File)227 4268 y(Name)e(Syn)m(tax')g(c)m (hapter)g(for)f(a)h(complete)g(description)d(of)j(the)f(full)f(\014le)g (\014ltering)g(syn)m(tax.)227 4416 y(When)e(op)s(ening)e(an)i(image,)g (a)h(rectangular)e(subset)g(of)h(the)g(ph)m(ysical)e(image)i(ma)m(y)h (b)s(e)e(op)s(ened)f(b)m(y)i(listing)227 4529 y(the)k(\014rst)e(and)h (last)g(pixel)f(in)g(eac)m(h)j(dimension)c(\(and)i(optional)f(pixel)g (skipping)f(factor\):)227 4765 y Fe(myimage.fits[101:200,301:)o(400]) 227 5001 y Fj(will)f(create)k(and)e(op)s(en)f(a)i(100x100)i(pixel)c (virtual)g(image)h(of)h(that)g(section)f(of)h(the)f(ph)m(ysical)f (image,)j(and)227 5114 y Fe(myimage.fits[*,-*])d Fj(op)s(ens)k(a)h (virtual)e(image)i(that)g(is)f(the)h(same)g(size)g(as)f(the)h(ph)m (ysical)f(image)h(but)227 5227 y(has)d(b)s(een)g(\015ipp)s(ed)e(in)h (the)h(v)m(ertical)h(direction.)227 5375 y(When)d(op)s(ening)f(a)h (table,)h(the)f(\014ltering)e(syn)m(tax)j(can)f(b)s(e)f(used)h(to)g (add)g(or)g(delete)g(columns)f(or)h(k)m(eyw)m(ords)227 5488 y(in)f(the)h(virtual)f(table:)39 b Fe(myfile.fits[events][col)j (!time;)k(PI)h(=)h(PHA*1.2])26 b Fj(op)s(ens)h(a)h(virtual)f(ta-)227 5601 y(ble)k(in)f(whic)m(h)g(the)i(TIME)f(column)f(has)h(b)s(een)g (deleted)g(and)g(a)g(new)g(PI)g(column)g(has)g(b)s(een)g(added)f(with) 227 5714 y(a)41 b(v)-5 b(alue)39 b(1.2)j(times)d(that)i(of)f(the)h(PHA) f(column.)69 b(Similarly)-8 b(,)39 b(one)i(can)f(\014lter)g(a)g(table)g (to)h(k)m(eep)g(only)p eop %%Page: 32 40 32 39 bop 0 299 a Fj(32)1379 b Fh(CHAPTER)30 b(5.)71 b(BASIC)30 b(CFITSIO)f(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)227 555 y Fj(those)35 b(ro)m(ws)e(that)i(satisfy)e(a)h(selection)g (criterion:)46 b Fe(myfile.fits[events][pha)c(>)47 b(50])33 b Fj(creates)j(and)227 668 y(op)s(ens)31 b(a)g(virtual)f(table)h(con)m (taining)g(only)f(those)i(ro)m(ws)f(with)f(a)h(PHA)h(v)-5 b(alue)30 b(greater)j(than)e(50.)44 b(A)31 b(large)227 781 y(n)m(um)m(b)s(er)d(of)h(b)s(o)s(olean)g(and)f(mathematical)i(op)s (erators)f(can)g(b)s(e)g(used)f(in)g(the)h(selection)g(expression.)39 b(One)227 894 y(can)25 b(also)f(\014lter)g(table)g(ro)m(ws)g(using)f ('Go)s(o)s(d)i(Time)e(In)m(terv)-5 b(al')25 b(extensions,)g(and)f (spatial)f(region)h(\014lters)g(as)g(in)227 1007 y Fe (myfile.fits[events][gtifi)o(lter)o(\(\)])14 b Fj(and)19 b Fe(myfile.fits[events][regfil)o(ter)o(\()42 b("stars.rng"\)])p Fj(.)227 1167 y(Finally)-8 b(,)31 b(table)g(columns)f(ma)m(y)i(b)s(e)f (binned)e(or)i(histogrammed)g(to)h(generate)h(a)e(virtual)f(image.)44 b(F)-8 b(or)32 b(ex-)227 1280 y(ample,)c Fe(myfile.fits[events][bin)41 b(\(X,Y\)=4])26 b Fj(will)e(result)j(in)f(a)i(2-dimensional)d(image)j (calculated)227 1393 y(b)m(y)35 b(binning)c(the)k(X)f(and)g(Y)h (columns)e(in)g(the)i(ev)m(en)m(t)h(table)e(with)f(a)i(bin)e(size)h(of) h(4)f(in)g(eac)m(h)h(dimension.)227 1506 y(The)30 b(TLMINn)g(and)f (TLMAXn)h(k)m(eyw)m(ords)h(will)d(b)s(e)h(used)h(b)m(y)g(default)g(to)h (determine)e(the)i(range)f(of)h(the)227 1619 y(image.)227 1779 y(A)j(single)e(program)h(can)g(op)s(en)g(the)h(same)f(FITS)g (\014le)f(more)i(than)f(once)h(and)f(then)g(treat)h(the)g(resulting)227 1892 y(\014ts\014le)29 b(p)s(oin)m(ters)g(as)h(though)g(they)g(w)m(ere) h(completely)f(indep)s(enden)m(t)e(FITS)h(\014les.)39 b(Using)30 b(this)f(facilit)m(y)-8 b(,)30 b(a)227 2005 y(program)i(can)f(op)s(en)g(a)h(FITS)f(\014le)f(t)m(wice,)j(mo)m(v)m(e) g(to)f(2)g(di\013eren)m(t)f(extensions)g(within)e(the)i(\014le,)g(and)g (then)227 2118 y(read)g(and)e(write)h(data)h(in)e(those)i(extensions)f (in)f(an)m(y)i(order.)0 2397 y Fi(2)81 b Fj(Create)31 b(and)f(op)s(en)f(a)i(new)f(empt)m(y)h(output)f(FITS)f(\014le.)227 2677 y Fe(int)47 b(fits_create_file)d(/)j(ffinit)418 2790 y(\(fitsfile)e(**fptr,)h(char)h(*filename,)e(>)i(int)g(*status\)) 227 3016 y(int)g(fits_create_diskfile)42 b(/)48 b(ffdkinit)418 3129 y(\(fitsfile)d(**fptr,)h(char)h(*filename,)e(>)i(int)g(*status\)) 227 3409 y Fj(An)36 b(error)h(will)d(b)s(e)i(returned)f(if)g(the)i(sp)s (eci\014ed)e(\014le)h(already)g(exists,)i(unless)d(the)i(\014lename)e (is)h(pre\014xed)227 3522 y(with)29 b(an)h(exclamation)g(p)s(oin)m(t)f (\(!\).)42 b(In)29 b(that)i(case)g(CFITSIO)d(will)g(o)m(v)m(erwrite)i (\(delete\))h(an)m(y)g(existing)e(\014le)227 3635 y(with)35 b(the)h(same)h(name.)57 b(Note)38 b(that)e(the)h(exclamation)f(p)s(oin) m(t)f(is)g(a)i(sp)s(ecial)d(UNIX)i(c)m(haracter)i(so)e(if)f(it)227 3748 y(is)d(used)f(on)h(the)h(command)f(line)f(it)h(m)m(ust)g(b)s(e)g (preceded)g(b)m(y)g(a)g(bac)m(kslash)g(to)i(force)e(the)h(UNIX)g(shell) d(to)227 3860 y(accept)i(the)f(c)m(haracter)h(as)e(part)g(of)h(the)g (\014lename.)227 4021 y(The)26 b(output)h(\014le)f(will)e(b)s(e)i (written)g(to)h(the)g('stdout')g(\014le)f(stream)h(if)f(a)h(dash)f(c)m (haracter)i(\('-'\))g(or)f(the)g(string)227 4134 y('stdout')34 b(is)e(giv)m(en)h(as)h(the)f(\014lename.)48 b(Similarly)-8 b(,)31 b('-.gz')k(or)e('stdout.gz')i(will)c(cause)i(the)h(\014le)e(to)i (b)s(e)e(gzip)227 4247 y(compressed)e(b)s(efore)g(it)g(is)g(written)f (out)i(to)g(the)f(stdout)h(stream.)227 4407 y(Optionally)-8 b(,)38 b(the)f(name)h(of)f(a)h(template)g(\014le)e(that)i(is)e(used)h (to)h(de\014ne)f(the)g(structure)g(of)g(the)h(new)f(\014le)227 4520 y(ma)m(y)i(b)s(e)f(sp)s(eci\014ed)e(in)h(paren)m(theses)i(follo)m (wing)d(the)j(output)e(\014le)h(name.)64 b(The)38 b(template)g(\014le)g (ma)m(y)h(b)s(e)227 4633 y(another)32 b(FITS)e(\014le,)h(in)f(whic)m(h) g(case)j(the)e(new)g(\014le,)g(at)h(the)g(time)f(it)f(is)h(op)s(ened,)g (will)d(b)s(e)j(an)g(exact)i(cop)m(y)227 4746 y(of)38 b(the)g(template)h(\014le)e(except)h(that)h(the)f(data)g(structures)g (\(images)g(and)f(tables\))h(will)d(b)s(e)j(\014lled)d(with)227 4858 y(zeros.)41 b(Alternativ)m(ely)-8 b(,)29 b(the)g(template)h (\014le)e(ma)m(y)h(b)s(e)f(an)h(ASCI)s(I)e(format)i(text)h(\014le)e (con)m(taining)h(directiv)m(es)227 4971 y(that)g(de\014ne)e(the)h(k)m (eyw)m(ords)g(to)g(b)s(e)g(created)h(in)d(eac)m(h)j(HDU)g(of)f(the)g (\014le.)39 b(See)28 b(the)g('Extended)f(File)g(Name)227 5084 y(Syn)m(tax')k(section)g(for)f(a)h(complete)f(description)f(of)h (the)h(template)g(\014le)e(syn)m(tax.)227 5245 y(The)g(\014ts)p 540 5245 28 4 v 33 w(create)p 809 5245 V 34 w(disk\014le)e(routine)i (is)g(similar)e(to)j(the)g(\014ts)p 2238 5245 V 32 w(create)p 2506 5245 V 34 w(\014le)f(routine)g(except)h(that)g(it)f(do)s(es)h(not) 227 5357 y(supp)s(ort)36 b(the)i(extended)g(\014lename)f(syn)m(tax)h (in)f(the)h(input)e(\014le)h(name.)63 b(This)36 b(routine)h(simply)e (tries)i(to)227 5470 y(create)f(the)e(sp)s(eci\014ed)e(\014le)h(on)g (magnetic)i(disk.)49 b(This)32 b(routine)h(is)g(mainly)f(for)i(use)f (in)g(cases)h(where)g(the)227 5583 y(\014lename)f(\(or)i(directory)e (path\))h(con)m(tains)g(square)g(or)g(curly)e(brac)m(k)m(et)k(c)m (haracters)f(that)f(w)m(ould)f(confuse)227 5696 y(the)e(extended)f (\014lename)g(parser.)p eop %%Page: 33 41 33 40 bop 0 299 a Fh(5.3.)72 b(HDU)31 b(A)m(CCESS)e(R)m(OUTINES)2488 b Fj(33)0 555 y Fi(3)81 b Fj(Close)27 b(a)g(previously)e(op)s(ened)i (FITS)g(\014le.)39 b(The)27 b(\014rst)f(routine)h(simply)e(closes)i (the)h(\014le,)f(whereas)g(the)h(second)227 668 y(one)41 b(also)f(DELETES)f(THE)h(FILE,)g(whic)m(h)f(can)i(b)s(e)e(useful)g(in)g (cases)i(where)e(a)i(FITS)e(\014le)h(has)g(b)s(een)227 781 y(partially)29 b(created,)i(but)f(then)g(an)g(error)g(o)s(ccurs)g (whic)m(h)g(prev)m(en)m(ts)g(it)g(from)g(b)s(eing)f(completed.)95 1033 y Fe(int)47 b(fits_close_file)d(/)j(ffclos)g(\(fitsfile)e(*fptr,)h (>)h(int)g(*status\))95 1258 y(int)g(fits_delete_file)d(/)j(ffdelt)f (\(fitsfile)g(*fptr,)g(>)h(int)g(*status\))0 1510 y Fi(4)81 b Fj(Return)21 b(the)i(name,)h(I/O)e(mo)s(de)g(\(READONL)-8 b(Y)24 b(or)e(READ)m(WRITE\),)i(and/or)e(the)g(\014le)g(t)m(yp)s(e)g (\(e.g.)40 b('\014le://',)227 1623 y('ftp://'\))32 b(of)f(the)f(op)s (ened)g(FITS)g(\014le.)95 1875 y Fe(int)47 b(fits_file_name)d(/)k (ffflnm)e(\(fitsfile)f(*fptr,)h(>)i(char)e(*filename,)f(int)i (*status\))95 2100 y(int)g(fits_file_mode)d(/)k(ffflmd)e(\(fitsfile)f (*fptr,)h(>)i(int)f(*iomode,)e(int)i(*status\))95 2326 y(int)g(fits_url_type)e(/)i(ffurlt)f(\(fitsfile)f(*fptr,)h(>)i(char)f (*urltype,)e(int)i(*status\))0 2659 y Ff(5.3)135 b(HDU)46 b(Access)e(Routines)0 2909 y Fj(The)30 b(follo)m(wing)f(functions)g(p)s (erform)g(op)s(erations)g(on)i(Header-Data)h(Units)e(\(HDUs\))i(as)e(a) h(whole.)0 3161 y Fi(1)81 b Fj(Mo)m(v)m(e)44 b(to)g(a)f(di\013eren)m(t) f(HDU)h(in)f(the)h(\014le.)76 b(The)43 b(\014rst)f(routine)f(mo)m(v)m (es)j(to)g(a)f(sp)s(eci\014ed)e(absolute)h(HDU)227 3273 y(n)m(um)m(b)s(er)g(\(starting)g(with)g(1)g(for)h(the)g(primary)d(arra) m(y\))k(in)d(the)i(FITS)f(\014le,)j(and)d(the)g(second)h(routine)227 3386 y(mo)m(v)m(es)35 b(a)e(relativ)m(e)g(n)m(um)m(b)s(er)f(HDUs)i (forw)m(ard)e(or)h(bac)m(kw)m(ard)h(from)f(the)g(curren)m(t)g(HDU.)h(A) f(n)m(ull)e(p)s(oin)m(ter)227 3499 y(ma)m(y)g(b)s(e)f(giv)m(en)g(for)g (the)g(hdut)m(yp)s(e)f(parameter)i(if)e(it's)h(v)-5 b(alue)30 b(is)f(not)i(needed.)40 b(The)30 b(third)e(routine)i(mo)m(v)m(es)227 3612 y(to)39 b(the)g(\(\014rst\))f(HDU)i(whic)m(h)d(has)h(the)h(sp)s (eci\014ed)d(extension)i(t)m(yp)s(e)h(and)f(EXTNAME)g(and)g(EXTVER)227 3725 y(k)m(eyw)m(ord)26 b(v)-5 b(alues)25 b(\(or)h(HDUNAME)h(and)e (HDUVER)h(k)m(eyw)m(ords\).)40 b(The)24 b(hdut)m(yp)s(e)h(parameter)h (ma)m(y)g(ha)m(v)m(e)227 3838 y(a)d(v)-5 b(alue)21 b(of)h(IMA)m(GE)p 935 3838 28 4 v 34 w(HDU,)h(ASCI)s(I)p 1476 3838 V 31 w(TBL,)f(BINAR)-8 b(Y)p 2101 3838 V 34 w(TBL,)22 b(or)g(ANY)p 2676 3838 V 34 w(HDU)g(where)g(ANY)p 3396 3838 V 33 w(HDU)h(means)227 3951 y(that)33 b(only)f(the)g(extname)i(and)d(extv)m(er)j(v)-5 b(alues)32 b(will)d(b)s(e)j(used)g(to)h(lo)s(cate)g(the)g(correct)g (extension.)47 b(If)32 b(the)227 4064 y(input)h(v)-5 b(alue)35 b(of)g(extv)m(er)h(is)e(0)i(then)e(the)i(EXTVER)e(k)m(eyw)m (ord)i(is)e(ignored)g(and)h(the)g(\014rst)f(HDU)i(with)e(a)227 4177 y(matc)m(hing)27 b(EXTNAME)h(\(or)f(HDUNAME\))i(k)m(eyw)m(ord)e (will)d(b)s(e)j(found.)38 b(If)27 b(no)f(matc)m(hing)h(HDU)h(is)e (found)227 4290 y(in)f(the)h(\014le)f(then)h(the)g(curren)m(t)g(HDU)g (will)e(remain)h(unc)m(hanged)g(and)h(a)g(status)g(=)g(BAD)p 3246 4290 V 33 w(HDU)p 3484 4290 V 34 w(NUM)h(will)227 4403 y(b)s(e)j(returned.)95 4654 y Fe(int)47 b(fits_movabs_hdu)d(/)j (ffmahd)286 4767 y(\(fitsfile)f(*fptr,)g(int)h(hdunum,)e(>)j(int)f (*hdutype,)e(int)i(*status\))95 4993 y(int)g(fits_movrel_hdu)d(/)j (ffmrhd)286 5106 y(\(fitsfile)f(*fptr,)g(int)h(nmove,)f(>)h(int)g (*hdutype,)e(int)i(*status\))95 5332 y(int)g(fits_movnam_hdu)d(/)j (ffmnhd)286 5445 y(\(fitsfile)f(*fptr,)g(int)h(hdutype,)e(char)i (*extname,)e(int)i(extver,)f(>)h(int)g(*status\))0 5696 y Fi(2)81 b Fj(Return)29 b(the)i(total)g(n)m(um)m(b)s(er)e(of)i(HDUs)f (in)g(the)g(FITS)g(\014le.)40 b(The)29 b(curren)m(t)i(HDU)g(remains)e (unc)m(hanged.)p eop %%Page: 34 42 34 41 bop 0 299 a Fj(34)1379 b Fh(CHAPTER)30 b(5.)71 b(BASIC)30 b(CFITSIO)f(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)95 555 y Fe(int)47 b(fits_get_num_hdus)c(/)48 b(ffthdu)286 668 y(\(fitsfile)e(*fptr,)g(>)h(int)g(*hdunum,)f(int)h(*status\))0 922 y Fi(3)81 b Fj(Return)31 b(the)h(n)m(um)m(b)s(er)f(of)h(the)h (curren)m(t)e(HDU)i(\(CHDU\))h(in)c(the)j(FITS)e(\014le)g(\(where)h (the)g(primary)f(arra)m(y)h(=)227 1034 y(1\).)42 b(This)28 b(function)h(returns)h(the)g(HDU)h(n)m(um)m(b)s(er)e(rather)h(than)h(a) f(status)h(v)-5 b(alue.)95 1288 y Fe(int)47 b(fits_get_hdu_num)d(/)j (ffghdn)286 1401 y(\(fitsfile)f(*fptr,)g(>)h(int)g(*hdunum\))0 1654 y Fi(4)81 b Fj(Return)38 b(the)h(t)m(yp)s(e)h(of)f(the)h(curren)m (t)f(HDU)h(in)e(the)h(FITS)g(\014le.)66 b(The)39 b(p)s(ossible)e(v)-5 b(alues)38 b(for)h(hdut)m(yp)s(e)f(are:)227 1767 y(IMA)m(GE)p 546 1767 28 4 v 34 w(HDU,)31 b(ASCI)s(I)p 1095 1767 V 32 w(TBL,)f(or)g(BINAR)-8 b(Y)p 1840 1767 V 34 w(TBL.)95 2021 y Fe(int)47 b(fits_get_hdu_type)c(/)48 b(ffghdt)286 2133 y(\(fitsfile)e(*fptr,)g(>)h(int)g(*hdutype,)e(int)i(*status\))0 2387 y Fi(5)81 b Fj(Cop)m(y)24 b(all)f(or)h(part)g(of)g(the)g(HDUs)h (in)e(the)h(FITS)g(\014le)f(asso)s(ciated)h(with)f(infptr)f(and)i(app)s (end)e(them)i(to)h(the)g(end)227 2500 y(of)f(the)f(FITS)f(\014le)h (asso)s(ciated)g(with)f(outfptr.)38 b(If)23 b('previous')f(is)g(true)h (\(not)h(0\),)i(then)d(an)m(y)g(HDUs)h(preceding)227 2613 y(the)35 b(curren)m(t)f(HDU)g(in)f(the)i(input)d(\014le)h(will)f (b)s(e)h(copied)h(to)h(the)f(output)g(\014le.)51 b(Similarly)-8 b(,)32 b('curren)m(t')j(and)227 2726 y('follo)m(wing')28 b(determine)g(whether)g(the)h(curren)m(t)g(HDU,)g(and/or)g(an)m(y)g (follo)m(wing)e(HDUs)j(in)d(the)i(input)e(\014le)227 2838 y(will)g(b)s(e)i(copied)h(to)g(the)g(output)f(\014le.)40 b(Th)m(us,)29 b(if)f(all)h(3)h(parameters)g(are)g(true,)g(then)g(the)f (en)m(tire)h(input)e(\014le)227 2951 y(will)33 b(b)s(e)h(copied.)55 b(On)35 b(exit,)h(the)g(curren)m(t)f(HDU)h(in)d(the)j(input)d(\014le)i (will)d(b)s(e)j(unc)m(hanged,)h(and)f(the)g(last)227 3064 y(HDU)c(in)e(the)i(output)f(\014le)f(will)f(b)s(e)i(the)g(curren)m (t)h(HDU.)95 3318 y Fe(int)47 b(fits_copy_file)d(/)k(ffcpfl)286 3431 y(\(fitsfile)e(*infptr,)f(fitsfile)h(*outfptr,)f(int)i(previous,)e (int)i(current,)477 3544 y(int)g(following,)e(>)j(int)f(*status\))0 3797 y Fi(6)81 b Fj(Cop)m(y)34 b(the)h(curren)m(t)f(HDU)h(from)f(the)g (FITS)g(\014le)g(asso)s(ciated)g(with)g(infptr)e(and)i(app)s(end)e(it)i (to)h(the)g(end)f(of)227 3910 y(the)39 b(FITS)e(\014le)g(asso)s(ciated) i(with)e(outfptr.)64 b(Space)38 b(ma)m(y)h(b)s(e)e(reserv)m(ed)i(for)f (MOREKEYS)f(additional)227 4023 y(k)m(eyw)m(ords)31 b(in)e(the)i (output)f(header.)95 4276 y Fe(int)47 b(fits_copy_hdu)e(/)i(ffcopy)286 4389 y(\(fitsfile)f(*infptr,)f(fitsfile)h(*outfptr,)f(int)i(morekeys,)e (>)j(int)f(*status\))0 4642 y Fi(7)81 b Fj(Cop)m(y)43 b(the)h(header)g(\(and)f(not)h(the)g(data\))h(from)e(the)h(CHDU)g(asso) s(ciated)g(with)f(infptr)e(to)k(the)f(CHDU)227 4755 y(asso)s(ciated)27 b(with)e(outfptr.)39 b(If)26 b(the)h(curren)m(t)f(output)g(HDU)h(is)f (not)g(completely)g(empt)m(y)-8 b(,)29 b(then)d(the)h(CHDU)227 4868 y(will)32 b(b)s(e)i(closed)g(and)g(a)h(new)f(HDU)h(will)d(b)s(e)i (app)s(ended)e(to)j(the)g(output)f(\014le.)52 b(An)34 b(empt)m(y)h(output)f(data)227 4981 y(unit)29 b(will)f(b)s(e)i(created) h(with)e(all)g(v)-5 b(alues)30 b(initially)d(=)j(0\).)95 5235 y Fe(int)47 b(fits_copy_header)d(/)j(ffcphd)286 5348 y(\(fitsfile)f(*infptr,)f(fitsfile)h(*outfptr,)f(>)i(int)g (*status\))0 5601 y Fi(8)81 b Fj(Delete)34 b(the)f(CHDU)h(in)e(the)h (FITS)f(\014le.)49 b(An)m(y)33 b(follo)m(wing)f(HDUs)h(will)e(b)s(e)h (shifted)g(forw)m(ard)h(in)f(the)h(\014le,)g(to)227 5714 y(\014ll)j(in)g(the)h(gap)h(created)g(b)m(y)g(the)f(deleted)g(HDU.)i (In)d(the)i(case)g(of)g(deleting)e(the)i(primary)d(arra)m(y)j(\(the)p eop %%Page: 35 43 35 42 bop 0 299 a Fh(5.4.)72 b(HEADER)31 b(KEYW)m(ORD)g(READ/WRITE)g(R) m(OUTINES)1495 b Fj(35)227 555 y(\014rst)30 b(HDU)h(in)e(the)i (\014le\))f(then)g(the)h(curren)m(t)f(primary)e(arra)m(y)j(will)d(b)s (e)i(replace)g(b)m(y)h(a)g(n)m(ull)d(primary)g(arra)m(y)227 668 y(con)m(taining)j(the)h(minim)m(um)c(set)k(of)g(required)d(k)m(eyw) m(ords)j(and)e(no)i(data.)44 b(If)31 b(there)g(are)h(more)f(extensions) 227 781 y(in)e(the)h(\014le)f(follo)m(wing)g(the)h(one)g(that)h(is)e (deleted,)h(then)g(the)g(the)g(CHDU)h(will)c(b)s(e)j(rede\014ned)e(to)j (p)s(oin)m(t)e(to)227 894 y(the)e(follo)m(wing)e(extension.)40 b(If)26 b(there)h(are)g(no)g(follo)m(wing)e(extensions)h(then)h(the)g (CHDU)g(will)d(b)s(e)i(rede\014ned)227 1007 y(to)36 b(p)s(oin)m(t)e(to) h(the)g(previous)e(HDU.)j(The)e(output)h(hdut)m(yp)s(e)e(parameter)i (returns)f(the)h(t)m(yp)s(e)g(of)f(the)h(new)227 1120 y(CHDU.)c(A)g(n)m(ull)d(p)s(oin)m(ter)h(ma)m(y)i(b)s(e)f(giv)m(en)h (for)f(hdut)m(yp)s(e)f(if)g(the)i(returned)e(v)-5 b(alue)30 b(is)f(not)i(needed.)95 1401 y Fe(int)47 b(fits_delete_hdu)d(/)j (ffdhdu)286 1514 y(\(fitsfile)f(*fptr,)g(>)h(int)g(*hdutype,)e(int)i (*status\))0 1872 y Ff(5.4)135 b(Header)46 b(Keyw)l(ord)g(Read/W)-11 b(rite)46 b(Routines)0 2128 y Fj(These)35 b(routines)f(read)g(or)h (write)g(k)m(eyw)m(ords)g(in)f(the)h(Curren)m(t)f(Header)h(Unit)f (\(CHU\).)i(Wild)e(card)g(c)m(haracters)0 2240 y(\(*,)28 b(?,)g(or)e(#\))h(ma)m(y)g(b)s(e)f(used)g(when)f(sp)s(ecifying)g(the)i (name)f(of)h(the)g(k)m(eyw)m(ord)g(to)g(b)s(e)f(read:)39 b(a)27 b(')10 b(?')39 b(will)24 b(matc)m(h)k(an)m(y)0 2353 y(single)33 b(c)m(haracter)i(at)g(that)f(p)s(osition)e(in)h(the)h (k)m(eyw)m(ord)h(name)f(and)f(a)h('*')h(will)d(matc)m(h)i(an)m(y)h (length)e(\(including)0 2466 y(zero\))d(string)e(of)h(c)m(haracters.)42 b(The)28 b('#')h(c)m(haracter)i(will)26 b(matc)m(h)k(an)m(y)f (consecutiv)m(e)h(string)e(of)h(decimal)f(digits)f(\(0)0 2579 y(-)35 b(9\).)55 b(When)35 b(a)g(wild)e(card)i(is)f(used)g(the)h (routine)f(will)e(only)i(searc)m(h)i(for)f(a)g(matc)m(h)h(from)e(the)h (curren)m(t)g(header)0 2692 y(p)s(osition)25 b(to)j(the)f(end)f(of)h (the)g(header)g(and)f(will)e(not)j(resume)g(the)g(searc)m(h)g(from)g (the)g(top)g(of)g(the)g(header)g(bac)m(k)g(to)0 2805 y(the)k(original)f(header)h(p)s(osition)e(as)j(is)e(done)h(when)f(no)h (wildcards)e(are)j(included)c(in)i(the)h(k)m(eyw)m(ord)h(name.)43 b(The)0 2918 y(\014ts)p 127 2918 28 4 v 32 w(read)p 331 2918 V 33 w(record)32 b(routine)f(ma)m(y)h(b)s(e)g(used)f(to)h(set)h (the)f(starting)g(p)s(osition)e(when)h(doing)g(wild)e(card)j(searc)m (hs.)46 b(A)0 3031 y(status)29 b(v)-5 b(alue)29 b(of)g(KEY)p 809 3031 V 32 w(NO)p 980 3031 V 33 w(EXIST)f(is)g(returned)f(if)h(the)h (sp)s(eci\014ed)e(k)m(eyw)m(ord)j(to)f(b)s(e)g(read)f(is)g(not)i(found) d(in)h(the)0 3144 y(header.)0 3459 y Fd(5.4.1)112 b(Keyw)m(ord)38 b(Reading)f(Routines)0 3684 y Fi(1)81 b Fj(Return)33 b(the)h(n)m(um)m(b)s(er)e(of)i(existing)f(k)m(eyw)m(ords)i(\(not)f (coun)m(ting)g(the)g(END)g(k)m(eyw)m(ord\))h(and)e(the)h(amoun)m(t)h (of)227 3797 y(space)e(curren)m(tly)e(a)m(v)-5 b(ailable)31 b(for)h(more)g(k)m(eyw)m(ords.)46 b(It)32 b(returns)e(morek)m(eys)j(=)f (-1)g(if)f(the)h(header)g(has)g(not)227 3910 y(y)m(et)27 b(b)s(een)d(closed.)39 b(Note)26 b(that)g(CFITSIO)d(will)g(dynamically) g(add)h(space)i(if)e(required)f(when)h(writing)f(new)227 4023 y(k)m(eyw)m(ords)32 b(to)g(a)f(header)g(so)h(in)e(practice)h (there)h(is)e(no)h(limit)e(to)j(the)f(n)m(um)m(b)s(er)f(of)i(k)m(eyw)m (ords)f(that)h(can)g(b)s(e)227 4136 y(added)e(to)h(a)f(header.)41 b(A)30 b(n)m(ull)e(p)s(oin)m(ter)i(ma)m(y)g(b)s(e)g(en)m(tered)h(for)f (the)g(morek)m(eys)h(parameter)g(if)e(it's)h(v)-5 b(alue)30 b(is)227 4249 y(not)h(needed.)95 4530 y Fe(int)47 b(fits_get_hdrspace)c (/)48 b(ffghsp)286 4642 y(\(fitsfile)e(*fptr,)g(>)h(int)g(*keysexist,)e (int)i(*morekeys,)e(int)i(*status\))0 4924 y Fi(2)81 b Fj(Return)28 b(the)h(sp)s(eci\014ed)e(k)m(eyw)m(ord.)41 b(In)29 b(the)g(\014rst)f(routine,)h(the)g(datat)m(yp)s(e)h(parameter)g (sp)s(eci\014es)d(the)i(desired)227 5036 y(returned)e(data)h(t)m(yp)s (e)g(of)g(the)g(k)m(eyw)m(ord)h(v)-5 b(alue)27 b(and)g(can)h(ha)m(v)m (e)h(one)f(of)g(the)g(follo)m(wing)e(sym)m(b)s(olic)h(constan)m(t)227 5149 y(v)-5 b(alues:)46 b(TSTRING,)33 b(TLOGICAL)f(\(==)h(in)m(t\),)i (TBYTE,)e(TSHOR)-8 b(T,)33 b(TUSHOR)-8 b(T,)32 b(TINT,)h(TUINT,)227 5262 y(TLONG,)39 b(TULONG,)f(TFLO)m(A)-8 b(T,)39 b(TDOUBLE,)g (TCOMPLEX,)e(and)h(TDBLCOMPLEX.)h(Within)227 5375 y(the)c(con)m(text)h (of)e(this)g(routine,)g(TSTRING)g(corresp)s(onds)e(to)j(a)g('c)m(har*') h(data)f(t)m(yp)s(e,)h(i.e.,)f(a)g(p)s(oin)m(ter)e(to)227 5488 y(a)e(c)m(haracter)i(arra)m(y)-8 b(.)43 b(Data)32 b(t)m(yp)s(e)f(con)m(v)m(ersion)g(will)d(b)s(e)i(p)s(erformed)g(for)g (n)m(umeric)g(v)-5 b(alues)30 b(if)g(the)g(k)m(eyw)m(ord)227 5601 y(v)-5 b(alue)35 b(do)s(es)g(not)g(ha)m(v)m(e)h(the)f(same)h(data) g(t)m(yp)s(e.)55 b(If)34 b(the)h(v)-5 b(alue)35 b(of)g(the)g(k)m(eyw)m (ord)h(is)e(unde\014ned)f(\(i.e.,)k(the)227 5714 y(v)-5 b(alue)30 b(\014eld)f(is)h(blank\))f(then)h(an)g(error)g(status)h(=)f (V)-10 b(ALUE)p 2280 5714 V 33 w(UNDEFINED)31 b(will)d(b)s(e)i (returned.)p eop %%Page: 36 44 36 43 bop 0 299 a Fj(36)1379 b Fh(CHAPTER)30 b(5.)71 b(BASIC)30 b(CFITSIO)f(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)227 555 y Fj(The)36 b(second)g(routine)f(returns)g(the)h(k)m(eyw)m(ord)h(v) -5 b(alue)35 b(as)h(a)h(c)m(haracter)h(string)d(\(a)h(literal)f(cop)m (y)i(of)f(what)227 668 y(is)d(in)f(the)i(v)-5 b(alue)33 b(\014eld\))f(regardless)h(of)g(the)h(in)m(trinsic)d(data)j(t)m(yp)s(e) g(of)f(the)h(k)m(eyw)m(ord.)50 b(The)33 b(third)f(routine)227 781 y(returns)d(the)i(en)m(tire)f(80-c)m(haracter)j(header)e(record)f (of)g(the)h(k)m(eyw)m(ord.)227 927 y(If)f(a)h(NULL)f(commen)m(t)i(p)s (oin)m(ter)d(is)g(supplied)f(then)i(the)g(commen)m(t)i(string)d(will)f (not)i(b)s(e)g(returned.)95 1160 y Fe(int)47 b(fits_read_key)e(/)i (ffgky)286 1273 y(\(fitsfile)f(*fptr,)g(int)h(datatype,)e(char)i (*keyname,)e(>)i(DTYPE)g(*value,)334 1386 y(char)g(*comment,)e(int)i (*status\))95 1612 y(int)g(fits_read_keyword)c(/)48 b(ffgkey)286 1725 y(\(fitsfile)e(*fptr,)g(char)g(*keyname,)g(>)h(char)g(*value,)f (char)g(*comment,)334 1838 y(int)h(*status\))95 2063 y(int)g(fits_read_card)d(/)k(ffgcrd)286 2176 y(\(fitsfile)e(*fptr,)g (char)g(*keyname,)g(>)h(char)g(*card,)f(int)h(*status\))0 2410 y Fi(3)81 b Fj(Return)27 b(the)h(n)m(th)h(header)f(record)g(in)f (the)h(CHU.)h(The)e(\014rst)h(k)m(eyw)m(ord)h(in)d(the)j(header)f(is)f (at)i(k)m(eyn)m(um)f(=)g(1;)i(if)227 2523 y(k)m(eyn)m(um)g(=)f(0)i (then)e(these)h(routines)f(simply)e(reset)k(the)f(in)m(ternal)e (CFITSIO)g(p)s(oin)m(ter)h(to)i(the)f(b)s(eginning)227 2635 y(of)f(the)g(header)g(so)g(that)g(subsequen)m(t)f(k)m(eyw)m(ord)h (op)s(erations)g(will)d(start)j(at)h(the)f(top)g(of)f(the)h(header)g (\(e.g.,)227 2748 y(prior)38 b(to)i(searc)m(hing)f(for)g(k)m(eyw)m (ords)h(using)e(wild)e(cards)j(in)f(the)i(k)m(eyw)m(ord)g(name\).)68 b(The)38 b(\014rst)h(routine)227 2861 y(returns)j(the)h(en)m(tire)g (80-c)m(haracter)i(header)e(record,)j(while)41 b(the)i(second)g (routine)f(parses)g(the)h(record)227 2974 y(and)35 b(returns)f(the)i (name,)h(v)-5 b(alue,)36 b(and)f(commen)m(t)h(\014elds)e(as)i(separate) g(c)m(haracter)h(strings.)54 b(If)35 b(a)h(NULL)227 3087 y(commen)m(t)c(p)s(oin)m(ter)d(is)g(giv)m(en)i(on)f(input,)f(then)h (the)g(commen)m(t)i(string)d(will)f(not)j(b)s(e)e(returned.)95 3320 y Fe(int)47 b(fits_read_record)d(/)j(ffgrec)286 3433 y(\(fitsfile)f(*fptr,)g(int)h(keynum,)e(>)j(char)f(*card,)f(int)h (*status\))95 3659 y(int)g(fits_read_keyn)d(/)k(ffgkyn)286 3772 y(\(fitsfile)e(*fptr,)g(int)h(keynum,)e(>)j(char)f(*keyname,)e (char)h(*value,)334 3885 y(char)h(*comment,)e(int)i(*status\))0 4118 y Fi(4)81 b Fj(Return)44 b(the)i(next)g(k)m(eyw)m(ord)g(whose)f (name)h(matc)m(hes)g(one)g(of)g(the)f(strings)g(in)f('inclist')g(but)h (do)s(es)g(not)227 4231 y(matc)m(h)31 b(an)m(y)g(of)g(the)f(strings)f (in)g('exclist'.)41 b(The)30 b(strings)f(in)g(inclist)f(and)i(exclist)g (ma)m(y)g(con)m(tain)h(wild)d(card)227 4344 y(c)m(haracters)34 b(\(*,)f(?,)f(and)f(#\))h(as)g(describ)s(ed)e(at)j(the)f(b)s(eginning)d (of)j(this)f(section.)45 b(This)30 b(routine)h(searc)m(hes)227 4457 y(from)k(the)g(curren)m(t)g(header)g(p)s(osition)e(to)j(the)f(end) f(of)h(the)h(header,)g(only)-8 b(,)36 b(and)e(do)s(es)h(not)g(con)m (tin)m(ue)h(the)227 4570 y(searc)m(h)c(from)e(the)h(top)g(of)g(the)g (header)g(bac)m(k)g(to)h(the)f(original)e(p)s(osition.)40 b(The)31 b(curren)m(t)f(header)h(p)s(osition)227 4683 y(ma)m(y)e(b)s(e)e(reset)h(with)f(the)h(\013grec)g(routine.)39 b(Note)29 b(that)g(nexc)f(ma)m(y)g(b)s(e)f(set)h(=)g(0)g(if)f(there)h (are)g(no)g(k)m(eyw)m(ords)227 4796 y(to)h(b)s(e)f(excluded.)38 b(This)27 b(routine)g(returns)g(status)h(=)g(KEY)p 2268 4796 28 4 v 32 w(NO)p 2439 4796 V 33 w(EXIST)f(if)g(a)i(matc)m(hing)f (k)m(eyw)m(ord)h(is)e(not)227 4909 y(found.)95 5142 y Fe(int)47 b(fits_find_nextkey)c(/)48 b(ffgnxk)286 5255 y(\(fitsfile)e(*fptr,)g(char)g(**inclist,)f(int)i(ninc,)g(char)f (**exclist,)334 5368 y(int)h(nexc,)f(>)i(char)e(*card,)h(int)94 b(*status\))0 5601 y Fi(5)81 b Fj(Return)25 b(the)h(ph)m(ysical)e (units)h(string)g(from)g(an)h(existing)f(k)m(eyw)m(ord.)39 b(This)25 b(routine)g(uses)g(a)h(lo)s(cal)g(con)m(v)m(en)m(tion,)227 5714 y(sho)m(wn)f(in)f(the)h(follo)m(wing)f(example,)i(in)e(whic)m(h)g (the)i(k)m(eyw)m(ord)f(units)f(are)i(enclosed)f(in)f(square)h(brac)m(k) m(ets)h(in)p eop %%Page: 37 45 37 44 bop 0 299 a Fh(5.4.)72 b(HEADER)31 b(KEYW)m(ORD)g(READ/WRITE)g(R) m(OUTINES)1495 b Fj(37)227 555 y(the)30 b(b)s(eginning)d(of)j(the)g(k)m (eyw)m(ord)g(commen)m(t)g(\014eld.)39 b(A)30 b(n)m(ull)e(string)g(is)h (returned)f(if)h(no)g(units)f(are)i(de\014ned)227 668 y(for)g(the)h(k)m(eyw)m(ord.)239 913 y Fe(VELOCITY=)809 b(12.3)46 b(/)i([km/s])e(orbital)g(speed)95 1139 y(int)h (fits_read_key_unit)c(/)48 b(ffgunt)286 1252 y(\(fitsfile)e(*fptr,)g (char)g(*keyname,)g(>)h(char)g(*unit,)f(int)h(*status\))0 1497 y Fi(6)81 b Fj(Concatenate)39 b(the)f(header)f(k)m(eyw)m(ords)h (in)f(the)g(CHDU)h(in)m(to)g(a)g(single)e(long)h(string)g(of)h(c)m (haracters.)64 b(This)227 1610 y(pro)m(vides)27 b(a)i(con)m(v)m(enien)m (t)g(w)m(a)m(y)g(of)g(passing)e(all)g(or)h(part)g(of)g(the)h(header)f (information)e(in)h(a)i(FITS)e(HDU)i(to)227 1723 y(other)i (subroutines.)38 b(Eac)m(h)31 b(80-c)m(haracter)h(\014xed-length)e(k)m (eyw)m(ord)g(record)g(is)f(app)s(ended)f(to)j(the)f(output)227 1836 y(c)m(haracter)j(string,)e(in)f(order,)h(with)f(no)h(in)m(terv)m (ening)g(separator)h(or)f(terminating)f(c)m(haracters.)45 b(The)31 b(last)227 1949 y(header)i(record)g(is)f(terminated)h(with)f (a)h(NULL)g(c)m(haracter.)50 b(This)32 b(routine)g(allo)s(cates)h (memory)g(for)g(the)227 2062 y(returned)c(c)m(haracter)j(arra)m(y)-8 b(,)32 b(so)f(the)f(calling)f(program)h(m)m(ust)g(free)h(the)g(memory)f (when)f(\014nished.)227 2210 y(Selected)g(k)m(eyw)m(ords)f(ma)m(y)h(b)s (e)e(excluded)g(from)h(the)g(returned)f(c)m(haracter)j(string.)39 b(If)27 b(the)i(second)f(param-)227 2323 y(eter)h(\(no)s(commen)m(ts\)) g(is)e(TR)m(UE)h(\(nonzero\))h(then)e(an)m(y)i(COMMENT,)f(HISTOR)-8 b(Y,)27 b(or)h(blank)f(k)m(eyw)m(ords)227 2435 y(in)i(the)i(header)f (will)e(not)i(b)s(e)g(copied)g(to)h(the)g(output)f(string.)227 2583 y(The)25 b('exclist')h(parameter)g(ma)m(y)g(b)s(e)f(used)g(to)h (supply)d(a)j(list)f(of)g(k)m(eyw)m(ords)h(that)h(are)f(to)g(b)s(e)f (excluded)f(from)227 2696 y(the)29 b(output)g(c)m(haracter)h(string.)40 b(Wild)27 b(card)i(c)m(haracters)h(\(*,)g(?,)f(and)g(#\))g(ma)m(y)g(b)s (e)f(used)g(in)g(the)h(excluded)227 2809 y(k)m(eyw)m(ord)h(names.)41 b(If)29 b(no)g(additional)f(k)m(eyw)m(ords)i(are)g(to)g(b)s(e)f (excluded,)g(then)g(set)h(nexc)g(=)f(0)h(and)f(sp)s(ecify)227 2922 y(NULL)i(for)f(the)g(the)h(**header)g(parameter.)95 3167 y Fe(int)47 b(fits_hdr2str)286 3280 y(\(fitsfile)f(*fptr,)g(int)h (nocomments,)d(char)j(**exclist,)e(int)i(nexc,)286 3393 y(>)h(char)e(**header,)g(int)h(*nkeys,)e(int)i(*status\))0 3681 y Fd(5.4.2)112 b(Keyw)m(ord)38 b(W)-9 b(riting)35 b(Routines)0 3888 y Fi(1)81 b Fj(W)-8 b(rite)31 b(a)h(k)m(eyw)m(ord)g (of)f(the)h(appropriate)e(data)i(t)m(yp)s(e)g(in)m(to)f(the)h(CHU.)f (The)g(\014rst)g(routine)f(simply)f(app)s(ends)227 4001 y(a)34 b(new)f(k)m(eyw)m(ord)h(whereas)f(the)g(second)h(routine)e(will) f(up)s(date)h(the)i(v)-5 b(alue)32 b(and)h(commen)m(t)h(\014elds)e(of)i (the)227 4114 y(k)m(eyw)m(ord)g(if)f(it)g(already)g(exists,)h (otherwise)f(it)g(app)s(ends)f(a)i(new)f(k)m(eyw)m(ord.)51 b(Note)35 b(that)f(the)g(address)e(to)227 4227 y(the)37 b(v)-5 b(alue,)37 b(and)e(not)i(the)f(v)-5 b(alue)35 b(itself,)i(m)m(ust)f(b)s(e)f(en)m(tered.)59 b(The)35 b(datat)m(yp)s(e)i(parameter)g(sp)s(eci\014es)e(the)227 4340 y(data)40 b(t)m(yp)s(e)f(of)g(the)g(k)m(eyw)m(ord)g(v)-5 b(alue)39 b(with)e(one)i(of)g(the)g(follo)m(wing)f(v)-5 b(alues:)57 b(TSTRING,)38 b(TLOGICAL)227 4452 y(\(==)e(in)m(t\),)i (TBYTE,)f(TSHOR)-8 b(T,)35 b(TUSHOR)-8 b(T,)36 b(TINT,)g(TUINT,)g (TLONG,)g(TULONG,)g(TFLO)m(A)-8 b(T,)227 4565 y(TDOUBLE.)24 b(Within)e(the)h(con)m(text)i(of)f(this)e(routine,)i(TSTRING)f(corresp) s(onds)f(to)i(a)g('c)m(har*')g(data)h(t)m(yp)s(e,)227 4678 y(i.e.,)j(a)e(p)s(oin)m(ter)g(to)h(a)f(c)m(haracter)i(arra)m(y)-8 b(.)40 b(A)27 b(n)m(ull)d(p)s(oin)m(ter)h(ma)m(y)i(b)s(e)f(en)m(tered)h (for)f(the)g(commen)m(t)h(parameter)227 4791 y(in)i(whic)m(h)g(case)j (the)e(k)m(eyw)m(ord)h(commen)m(t)h(\014eld)d(will)e(b)s(e)j(unmo)s (di\014ed)d(or)k(left)f(blank.)95 5036 y Fe(int)47 b(fits_write_key)d (/)k(ffpky)286 5149 y(\(fitsfile)e(*fptr,)g(int)h(datatype,)e(char)i (*keyname,)e(DTYPE)h(*value,)477 5262 y(char)h(*comment,)e(>)j(int)f (*status\))95 5488 y(int)g(fits_update_key)d(/)j(ffuky)286 5601 y(\(fitsfile)f(*fptr,)g(int)h(datatype,)e(char)i(*keyname,)e (DTYPE)h(*value,)477 5714 y(char)h(*comment,)e(>)j(int)f(*status\))p eop %%Page: 38 46 38 45 bop 0 299 a Fj(38)1379 b Fh(CHAPTER)30 b(5.)71 b(BASIC)30 b(CFITSIO)f(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)0 555 y Fi(2)81 b Fj(W)-8 b(rite)43 b(a)h(k)m(eyw)m(ord)f(with)f(a)i(n)m (ull)d(or)i(unde\014ned)e(v)-5 b(alue)42 b(\(i.e.,)47 b(the)d(v)-5 b(alue)42 b(\014eld)g(in)g(the)h(k)m(eyw)m(ord)h(is)e (left)227 668 y(blank\).)69 b(The)40 b(\014rst)f(routine)g(simply)f (app)s(ends)g(a)j(new)e(k)m(eyw)m(ord)i(whereas)f(the)g(second)g (routine)g(will)227 781 y(up)s(date)27 b(the)h(v)-5 b(alue)28 b(and)f(commen)m(t)i(\014elds)d(of)i(the)g(k)m(eyw)m(ord)g(if)f(it)g (already)h(exists,)g(otherwise)f(it)h(app)s(ends)227 894 y(a)h(new)g(k)m(eyw)m(ord.)40 b(A)29 b(n)m(ull)e(p)s(oin)m(ter)h (ma)m(y)h(b)s(e)g(en)m(tered)g(for)g(the)g(commen)m(t)g(parameter)h(in) d(whic)m(h)h(case)i(the)227 1007 y(k)m(eyw)m(ord)h(commen)m(t)h (\014eld)c(will)g(b)s(e)i(unmo)s(di\014ed)d(or)k(left)f(blank.)95 1261 y Fe(int)47 b(fits_write_key_null)c(/)k(ffpkyu)286 1374 y(\(fitsfile)f(*fptr,)g(char)g(*keyname,)g(char)g(*comment,)g(>)h (int)g(*status\))95 1599 y(int)g(fits_update_key_null)c(/)k(ffukyu)286 1712 y(\(fitsfile)f(*fptr,)g(char)g(*keyname,)g(char)g(*comment,)g(>)h (int)g(*status\))0 1966 y Fi(3)81 b Fj(W)-8 b(rite)39 b(\(app)s(end\))f(a)h(COMMENT)g(or)g(HISTOR)-8 b(Y)38 b(k)m(eyw)m(ord)i(to)f(the)g(CHU.)h(The)e(commen)m(t)i(or)f(history)227 2079 y(string)30 b(will)d(b)s(e)j(con)m(tin)m(ued)g(o)m(v)m(er)i(m)m (ultiple)c(k)m(eyw)m(ords)j(if)e(it)h(is)f(longer)h(than)g(70)i(c)m (haracters.)95 2333 y Fe(int)47 b(fits_write_comment)c(/)48 b(ffpcom)286 2446 y(\(fitsfile)e(*fptr,)g(char)g(*comment,)g(>)h(int)g (*status\))95 2672 y(int)g(fits_write_history)c(/)48 b(ffphis)286 2785 y(\(fitsfile)e(*fptr,)g(char)g(*history,)g(>)h(int)g (*status\))0 3039 y Fi(4)81 b Fj(W)-8 b(rite)28 b(the)h(D)m(A)-8 b(TE)29 b(k)m(eyw)m(ord)g(to)g(the)g(CHU.)f(The)g(k)m(eyw)m(ord)h(v)-5 b(alue)28 b(will)d(con)m(tain)k(the)g(curren)m(t)f(system)g(date)227 3152 y(as)k(a)g(c)m(haracter)h(string)d(in)g('yyyy-mm-ddThh:mm:ss')f (format.)44 b(If)31 b(a)h(D)m(A)-8 b(TE)32 b(k)m(eyw)m(ord)g(already)f (exists)227 3264 y(in)c(the)g(header,)i(then)e(this)f(routine)h(will)e (simply)g(up)s(date)i(the)h(k)m(eyw)m(ord)g(v)-5 b(alue)27 b(with)f(the)i(curren)m(t)g(date.)95 3518 y Fe(int)47 b(fits_write_date)d(/)j(ffpdat)286 3631 y(\(fitsfile)f(*fptr,)g(>)h (int)g(*status\))0 3885 y Fi(5)81 b Fj(W)-8 b(rite)33 b(a)h(user)f(sp)s(eci\014ed)f(k)m(eyw)m(ord)i(record)f(in)m(to)g(the)h (CHU.)g(This)d(is)i(a)h(lo)m(w{lev)m(el)f(routine)g(whic)m(h)f(can)i(b) s(e)227 3998 y(used)f(to)h(write)e(an)m(y)i(arbitrary)e(record)h(in)m (to)h(the)f(header.)50 b(The)32 b(record)i(m)m(ust)f(conform)g(to)h (the)g(all)e(the)227 4111 y(FITS)e(format)h(requiremen)m(ts.)95 4365 y Fe(int)47 b(fits_write_record)c(/)48 b(ffprec)286 4478 y(\(fitsfile)e(*fptr,)g(char)g(*card,)g(>)i(int)f(*status\))0 4732 y Fi(6)81 b Fj(Up)s(date)34 b(an)g(80-c)m(haracter)j(record)e(in)e (the)h(CHU.)h(If)f(a)h(k)m(eyw)m(ord)f(with)g(the)g(input)f(name)h (already)g(exists,)227 4845 y(then)f(it)g(is)f(o)m(v)m(erwritten)h(b)m (y)g(the)g(v)-5 b(alue)33 b(of)g(card.)49 b(This)31 b(could)h(mo)s (dify)f(the)j(k)m(eyw)m(ord)f(name)g(as)h(w)m(ell)e(as)227 4958 y(the)e(v)-5 b(alue)29 b(and)f(commen)m(t)j(\014elds.)39 b(If)29 b(the)g(k)m(eyw)m(ord)h(do)s(esn't)f(already)g(exist)g(then)h (a)f(new)g(k)m(eyw)m(ord)h(card)227 5070 y(is)g(app)s(ended)e(to)j(the) g(header.)95 5324 y Fe(int)47 b(fits_update_card)d(/)j(ffucrd)286 5437 y(\(fitsfile)f(*fptr,)g(char)g(*keyname,)g(char)g(*card,)g(>)i (int)f(*status\))0 5691 y Fi(7)81 b Fj(Mo)s(dify)29 b(\(o)m(v)m (erwrite\))i(the)g(commen)m(t)g(\014eld)e(of)i(an)f(existing)f(k)m(eyw) m(ord.)p eop %%Page: 39 47 39 46 bop 0 299 a Fh(5.5.)72 b(PRIMAR)-8 b(Y)31 b(ARRA)-8 b(Y)31 b(OR)f(IMA)m(GE)h(EXTENSION)f(I/O)g(R)m(OUTINES)1011 b Fj(39)95 555 y Fe(int)47 b(fits_modify_comment)c(/)k(ffmcom)286 668 y(\(fitsfile)f(*fptr,)g(char)g(*keyname,)g(char)g(*comment,)g(>)h (int)g(*status\))0 907 y Fi(8)81 b Fj(W)-8 b(rite)32 b(the)g(ph)m(ysical)f(units)g(string)g(in)m(to)h(an)g(existing)f(k)m (eyw)m(ord.)46 b(This)31 b(routine)g(uses)h(a)g(lo)s(cal)g(con)m(v)m (en)m(tion,)227 1020 y(sho)m(wn)g(in)f(the)i(follo)m(wing)e(example,)i (in)e(whic)m(h)g(the)i(k)m(eyw)m(ord)g(units)e(are)i(enclosed)f(in)f (square)h(brac)m(k)m(ets)227 1133 y(in)d(the)i(b)s(eginning)d(of)i(the) h(k)m(eyw)m(ord)g(commen)m(t)g(\014eld.)239 1372 y Fe(VELOCITY=)809 b(12.3)46 b(/)i([km/s])e(orbital)g(speed)95 1598 y(int)h (fits_write_key_unit)c(/)k(ffpunt)286 1711 y(\(fitsfile)f(*fptr,)g (char)g(*keyname,)g(char)g(*unit,)g(>)i(int)f(*status\))0 1950 y Fi(9)81 b Fj(Rename)30 b(an)h(existing)e(k)m(eyw)m(ord,)i (preserving)e(the)h(curren)m(t)h(v)-5 b(alue)29 b(and)h(commen)m(t)i (\014elds.)95 2189 y Fe(int)47 b(fits_modify_name)d(/)j(ffmnam)286 2302 y(\(fitsfile)f(*fptr,)g(char)g(*oldname,)g(char)g(*newname,)g(>)h (int)g(*status\))0 2541 y Fi(10)f Fj(Delete)36 b(a)f(k)m(eyw)m(ord)g (record.)54 b(The)34 b(space)i(o)s(ccupied)d(b)m(y)i(the)g(k)m(eyw)m (ord)g(is)f(reclaimed)g(b)m(y)g(mo)m(ving)h(all)f(the)227 2654 y(follo)m(wing)d(header)i(records)f(up)g(one)h(ro)m(w)f(in)g(the)g (header.)48 b(The)32 b(\014rst)g(routine)f(deletes)i(a)g(k)m(eyw)m(ord) g(at)h(a)227 2767 y(sp)s(eci\014ed)22 b(p)s(osition)g(in)h(the)h (header)f(\(the)i(\014rst)e(k)m(eyw)m(ord)h(is)f(at)h(p)s(osition)e (1\),)k(whereas)e(the)g(second)g(routine)227 2880 y(deletes)29 b(a)g(sp)s(eci\014cally)d(named)i(k)m(eyw)m(ord.)41 b(Wild)27 b(card)h(c)m(haracters)i(ma)m(y)f(b)s(e)f(used)g(when)f(sp)s(ecifying)g (the)227 2993 y(name)k(of)f(the)h(k)m(eyw)m(ord)g(to)g(b)s(e)e (deleted.)95 3232 y Fe(int)47 b(fits_delete_record)c(/)48 b(ffdrec)286 3345 y(\(fitsfile)e(*fptr,)g(int)142 b(keynum,)94 b(>)47 b(int)g(*status\))95 3571 y(int)g(fits_delete_key)d(/)j(ffdkey) 286 3684 y(\(fitsfile)f(*fptr,)g(char)g(*keyname,)g(>)h(int)g (*status\))0 4014 y Ff(5.5)135 b(Primary)46 b(Arra)l(y)f(or)g(IMA)l(GE) f(Extension)i(I/O)f(Routines)0 4264 y Fj(These)22 b(routines)f(read)i (or)f(write)g(data)h(v)-5 b(alues)22 b(in)f(the)h(primary)f(data)i (arra)m(y)g(\(i.e.,)i(the)d(\014rst)g(HDU)h(in)e(a)i(FITS)e(\014le\))0 4377 y(or)32 b(an)g(IMA)m(GE)h(extension.)46 b(There)31 b(are)i(also)f(routines)f(to)i(get)g(information)d(ab)s(out)i(the)g (data)h(t)m(yp)s(e)g(and)e(size)0 4490 y(of)c(the)g(image.)40 b(Users)27 b(should)e(also)i(read)g(the)g(follo)m(wing)e(c)m(hapter)j (on)f(the)g(CFITSIO)e(iterator)j(function)d(whic)m(h)0 4603 y(pro)m(vides)32 b(a)i(more)f(`ob)5 b(ject)35 b(orien)m(ted')e (metho)s(d)g(of)g(reading)f(and)h(writing)e(images.)50 b(The)32 b(iterator)i(function)e(is)0 4716 y(a)f(little)f(more)h (complicated)f(to)i(use,)f(but)f(the)h(adv)-5 b(an)m(tages)32 b(are)f(that)h(it)e(usually)f(tak)m(es)j(less)e(co)s(de)h(to)g(p)s (erform)0 4829 y(the)j(same)h(op)s(eration,)f(and)f(the)i(resulting)d (program)h(oftens)i(runs)d(faster)i(b)s(ecause)g(the)h(FITS)e(\014les)g (are)h(read)0 4942 y(and)c(written)f(using)g(the)i(most)f(e\016cien)m (t)h(blo)s(c)m(k)f(size.)0 5102 y(C)25 b(programmers)h(should)e(note)i (that)g(the)h(ordering)d(of)i(arra)m(ys)g(in)f(FITS)g(\014les,)h(and)f (hence)h(in)f(all)f(the)i(CFITSIO)0 5215 y(calls,)38 b(is)e(more)h(similar)e(to)i(the)h(dimensionalit)m(y)c(of)j(arra)m(ys)g (in)f(F)-8 b(ortran)38 b(rather)f(than)f(C.)h(F)-8 b(or)38 b(instance)f(if)f(a)0 5328 y(FITS)28 b(image)h(has)f(NAXIS1)h(=)f(100)i (and)e(NAXIS2)h(=)f(50,)i(then)e(a)h(2-D)h(arra)m(y)f(just)f(large)h (enough)f(to)i(hold)d(the)0 5441 y(image)k(should)d(b)s(e)i(declared)g (as)g(arra)m(y[50][100])k(and)c(not)h(as)f(arra)m(y[100][50].)0 5601 y(The)h(`datat)m(yp)s(e')h(parameter)g(sp)s(eci\014es)d(the)j (data)g(t)m(yp)s(e)f(of)g(the)g(`n)m(ulv)-5 b(al')30 b(and)h(`arra)m(y')h(p)s(oin)m(ters)e(and)g(can)i(ha)m(v)m(e)0 5714 y(one)h(of)g(the)g(follo)m(wing)e(v)-5 b(alues:)45 b(TBYTE,)33 b(TSBYTE,)f(TSHOR)-8 b(T,)32 b(TUSHOR)-8 b(T,)32 b(TINT,)h(TUINT,)f(TLONG,)p eop %%Page: 40 48 40 47 bop 0 299 a Fj(40)1379 b Fh(CHAPTER)30 b(5.)71 b(BASIC)30 b(CFITSIO)f(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)0 555 y Fj(TLONGLONG,)c(TULONG,)g(TFLO)m(A)-8 b(T,)27 b(TDOUBLE.)f (Automatic)h(data)g(t)m(yp)s(e)g(con)m(v)m(ersion)f(is)f(p)s(erformed)g (if)0 668 y(the)j(data)h(t)m(yp)s(e)f(of)f(the)i(FITS)e(arra)m(y)h (\(as)g(de\014ned)f(b)m(y)h(the)g(BITPIX)f(k)m(eyw)m(ord\))i(di\013ers) d(from)i(that)g(sp)s(eci\014ed)e(b)m(y)0 781 y('datat)m(yp)s(e'.)54 b(The)34 b(data)h(v)-5 b(alues)34 b(are)g(also)h(automatically)f (scaled)g(b)m(y)g(the)h(BSCALE)f(and)f(BZER)m(O)h(k)m(eyw)m(ord)0 894 y(v)-5 b(alues)30 b(as)g(they)h(are)g(b)s(eing)e(read)h(or)g (written)g(in)f(the)h(FITS)g(arra)m(y)-8 b(.)0 1147 y Fi(1)81 b Fj(Get)39 b(the)f(data)h(t)m(yp)s(e)f(or)g(equiv)-5 b(alen)m(t)37 b(data)i(t)m(yp)s(e)f(of)g(the)h(image.)64 b(The)37 b(\014rst)g(routine)g(returns)g(the)h(ph)m(ys-)227 1260 y(ical)j(data)g(t)m(yp)s(e)h(of)f(the)g(FITS)f(image,)k(as)e(giv)m (en)f(b)m(y)g(the)g(BITPIX)g(k)m(eyw)m(ord,)j(with)c(allo)m(w)m(ed)h(v) -5 b(alues)227 1373 y(of)44 b(BYTE)p 609 1373 28 4 v 33 w(IMG)g(\(8\),)k(SHOR)-8 b(T)p 1376 1373 V 32 w(IMG)44 b(\(16\),)49 b(LONG)p 2140 1373 V 33 w(IMG)44 b(\(32\),)49 b(FLO)m(A)-8 b(T)p 2948 1373 V 33 w(IMG)44 b(\(-32\),)49 b(and)43 b(DOU-)227 1486 y(BLE)p 415 1486 V 33 w(IMG)f(\(-64\).)75 b(The)40 b(second)i(routine)e(is)g(similar,)i(except)g(that)g(if)e(the) h(image)h(pixel)d(v)-5 b(alues)41 b(are)227 1599 y(scaled,)28 b(with)f(non-default)f(v)-5 b(alues)27 b(for)g(the)h(BZER)m(O)f(and)g (BSCALE)g(k)m(eyw)m(ords,)h(then)f(the)h(routine)f(will)227 1712 y(return)35 b(the)h('equiv)-5 b(alen)m(t')35 b(data)h(t)m(yp)s(e)g (that)g(is)f(needed)g(to)i(store)f(the)g(scaled)f(v)-5 b(alues.)56 b(F)-8 b(or)36 b(example,)h(if)227 1824 y(BITPIX)27 b(=)f(16)i(and)e(BSCALE)h(=)f(0.1)i(then)f(the)g(equiv)-5 b(alen)m(t)26 b(data)i(t)m(yp)s(e)f(is)f(FLO)m(A)-8 b(T)p 3196 1824 V 33 w(IMG.)28 b(Similarly)23 b(if)227 1937 y(BITPIX)28 b(=)g(16,)i(BSCALE)d(=)h(1,)h(and)f(BZER)m(O)g(=)g(32768,)j (then)d(the)g(the)h(pixel)d(v)-5 b(alues)28 b(span)f(the)i(range)227 2050 y(of)i(an)f(unsigned)e(short)i(in)m(teger)h(and)f(the)h(returned)e (data)i(t)m(yp)s(e)f(will)e(b)s(e)i(USHOR)-8 b(T)p 3168 2050 V 32 w(IMG.)95 2303 y Fe(int)47 b(fits_get_img_type)c(/)48 b(ffgidt)286 2416 y(\(fitsfile)e(*fptr,)g(>)h(int)g(*bitpix,)f(int)h (*status\))95 2642 y(int)g(fits_get_img_equivtype)42 b(/)48 b(ffgiet)286 2755 y(\(fitsfile)e(*fptr,)g(>)h(int)g(*bitpix,)f (int)h(*status\))0 3008 y Fi(2)81 b Fj(Get)34 b(the)g(n)m(um)m(b)s(er)e (of)i(dimensions,)e(and/or)i(the)g(size)f(of)h(eac)m(h)h(dimension)c (in)h(the)i(image)g(.)50 b(The)33 b(n)m(um)m(b)s(er)227 3121 y(of)h(axes)f(in)f(the)h(image)h(is)e(giv)m(en)h(b)m(y)g(naxis,)g (and)g(the)g(size)g(of)g(eac)m(h)i(dimension)30 b(is)i(giv)m(en)h(b)m (y)g(the)h(naxes)227 3234 y(arra)m(y)d(\(a)g(maxim)m(um)f(of)g(maxdim)f (dimensions)f(will)f(b)s(e)j(returned\).)95 3487 y Fe(int)47 b(fits_get_img_dim)d(/)j(ffgidm)286 3600 y(\(fitsfile)f(*fptr,)g(>)h (int)g(*naxis,)f(int)h(*status\))95 3826 y(int)g(fits_get_img_size)c(/) 48 b(ffgisz)286 3939 y(\(fitsfile)e(*fptr,)g(int)h(maxdim,)e(>)j(long)f (*naxes,)e(int)i(*status\))95 4164 y(int)g(fits_get_img_param)c(/)48 b(ffgipr)286 4277 y(\(fitsfile)e(*fptr,)g(int)h(maxdim,)e(>)j(int)f (*bitpix,)e(int)i(*naxis,)f(long)h(*naxes,)334 4390 y(int)g(*status\))0 4643 y Fi(3)81 b Fj(Create)23 b(a)f(new)g(primary)e(arra)m(y)j(or)f (IMA)m(GE)i(extension)d(with)g(a)i(sp)s(eci\014ed)e(data)i(t)m(yp)s(e)f (and)g(size.)37 b(If)22 b(the)h(FITS)227 4756 y(\014le)29 b(is)g(curren)m(tly)f(empt)m(y)i(then)g(a)g(primary)e(arra)m(y)i(is)f (created,)i(otherwise)e(a)h(new)f(IMA)m(GE)i(extension)e(is)227 4869 y(app)s(ended)g(to)i(the)g(\014le.)95 5122 y Fe(int)47 b(fits_create_img)d(/)j(ffcrim)286 5235 y(\()h(fitsfile)d(*fptr,)h(int) h(bitpix,)f(int)h(naxis,)f(long)h(*naxes,)f(>)h(int)g(*status\))0 5488 y Fi(4)81 b Fj(W)-8 b(rite)39 b(a)g(rectangular)f(subimage)g(\(or) h(the)g(whole)f(image\))h(to)g(the)g(FITS)f(data)h(arra)m(y)-8 b(.)67 b(The)38 b(fpixel)f(and)227 5601 y(lpixel)27 b(arra)m(ys)j(giv)m (e)g(the)g(co)s(ordinates)f(of)g(the)h(\014rst)f(\(lo)m(w)m(er)h(left)f (corner\))h(and)f(last)g(\(upp)s(er)f(righ)m(t)h(corner\))227 5714 y(pixels)g(in)g(FITS)h(image)g(to)h(b)s(e)f(written)f(to.)p eop %%Page: 41 49 41 48 bop 0 299 a Fh(5.5.)72 b(PRIMAR)-8 b(Y)31 b(ARRA)-8 b(Y)31 b(OR)f(IMA)m(GE)h(EXTENSION)f(I/O)g(R)m(OUTINES)1011 b Fj(41)95 555 y Fe(int)47 b(fits_write_subset)c(/)48 b(ffpss)286 668 y(\(fitsfile)e(*fptr,)g(int)h(datatype,)e(long)i (*fpixel,)e(long)i(*lpixel,)334 781 y(DTYPE)f(*array,)g(>)i(int)f (*status\))0 1018 y Fi(5)81 b Fj(W)-8 b(rite)38 b(pixels)f(in)m(to)h (the)h(FITS)f(data)h(arra)m(y)-8 b(.)66 b('fpixel')37 b(is)g(an)h(arra)m(y)h(of)g(length)f(NAXIS)g(whic)m(h)f(giv)m(es)i(the) 227 1131 y(co)s(ordinate)k(of)g(the)g(starting)f(pixel)f(to)j(b)s(e)e (written)g(to,)k(suc)m(h)d(that)g(fpixel[0])f(is)g(in)f(the)i(range)g (1)g(to)227 1244 y(NAXIS1,)30 b(fpixel[1])d(is)g(in)g(the)i(range)g(1)f (to)h(NAXIS2,)h(etc.)41 b(The)28 b(\014rst)f(routine)h(simply)d(writes) j(the)g(arra)m(y)227 1357 y(of)e(pixels)d(to)j(the)g(FITS)f(\014le)f (\(doing)h(data)h(t)m(yp)s(e)g(con)m(v)m(ersion)f(if)g(necessary\))h (whereas)f(the)g(second)h(routine)227 1470 y(will)f(substitute)i(the)h (appropriate)f(FITS)g(n)m(ull)f(v)-5 b(alue)27 b(for)h(an)m(y)g(elemen) m(ts)g(whic)m(h)f(are)h(equal)f(to)i(the)f(input)227 1582 y(v)-5 b(alue)25 b(of)h(n)m(ulv)-5 b(al)23 b(\(note)j(that)g(this) f(parameter)g(giv)m(es)h(the)g(address)e(of)h(the)h(n)m(ull)d(v)-5 b(alue,)26 b(not)g(the)f(n)m(ull)e(v)-5 b(alue)227 1695 y(itself)7 b(\).)45 b(F)-8 b(or)33 b(in)m(teger)f(FITS)f(arra)m(ys,)i (the)g(FITS)e(n)m(ull)f(v)-5 b(alue)31 b(is)g(de\014ned)g(b)m(y)h(the)g (BLANK)g(k)m(eyw)m(ord)h(\(an)227 1808 y(error)h(is)f(returned)h(if)f (the)h(BLANK)h(k)m(eyw)m(ord)f(do)s(esn't)h(exist\).)52 b(F)-8 b(or)35 b(\015oating)f(p)s(oin)m(t)g(FITS)f(arra)m(ys)i(the)227 1921 y(sp)s(ecial)29 b(IEEE)h(NaN)h(\(Not-a-Num)m(b)s(er\))h(v)-5 b(alue)30 b(will)e(b)s(e)h(written)h(in)m(to)g(the)h(FITS)e(\014le.)40 b(If)30 b(a)h(n)m(ull)d(p)s(oin)m(ter)227 2034 y(is)40 b(en)m(tered)h(for)f(n)m(ulv)-5 b(al,)42 b(then)e(the)g(n)m(ull)f(v)-5 b(alue)40 b(is)f(ignored)h(and)f(this)h(routine)f(b)s(eha)m(v)m(es)i (the)g(same)g(as)227 2147 y(\014ts)p 354 2147 28 4 v 33 w(write)p 590 2147 V 32 w(pix.)95 2384 y Fe(int)47 b(fits_write_pix)d(/)k(ffppx)286 2497 y(\(fitsfile)e(*fptr,)g(int)h (datatype,)e(long)i(*fpixel,)e(long)i(nelements,)334 2610 y(DTYPE)f(*array,)g(int)h(*status\);)95 2836 y(int)g (fits_write_pixnull)c(/)48 b(ffppxn)286 2949 y(\(fitsfile)e(*fptr,)g (int)h(datatype,)e(long)i(*fpixel,)e(long)i(nelements,)334 3061 y(DTYPE)f(*array,)g(DTYPE)h(*nulval,)e(>)j(int)f(*status\);)0 3298 y Fi(6)81 b Fj(Set)24 b(FITS)g(data)i(arra)m(y)f(elemen)m(ts)g (equal)f(to)h(the)g(appropriate)e(n)m(ull)g(pixel)g(v)-5 b(alue.)38 b(F)-8 b(or)25 b(in)m(teger)g(FITS)f(arra)m(ys,)227 3411 y(the)34 b(FITS)e(n)m(ull)f(v)-5 b(alue)33 b(is)f(de\014ned)g(b)m (y)h(the)h(BLANK)f(k)m(eyw)m(ord)h(\(an)f(error)g(is)f(returned)g(if)g (the)i(BLANK)227 3524 y(k)m(eyw)m(ord)23 b(do)s(esn't)g(exist\).)38 b(F)-8 b(or)23 b(\015oating)f(p)s(oin)m(t)g(FITS)g(arra)m(ys)g(the)h (sp)s(ecial)e(IEEE)h(NaN)h(\(Not-a-Num)m(b)s(er\))227 3637 y(v)-5 b(alue)33 b(will)d(b)s(e)j(written)f(in)m(to)h(the)h(FITS)e (\014le.)48 b(Note)34 b(that)g('\014rstelem')f(is)f(a)i(scalar)f (giving)f(the)h(o\013set)h(to)227 3750 y(the)d(\014rst)e(pixel)g(to)i (b)s(e)f(written)f(in)h(the)g(equiv)-5 b(alen)m(t)30 b(1-dimensional)e(arra)m(y)j(of)g(image)f(pixels.)95 3987 y Fe(int)47 b(fits_write_null_img)c(/)k(ffpprn)286 4100 y(\(fitsfile)f(*fptr,)g(long)g(firstelem,)f(long)i(nelements,)e(>) i(int)g(*status\))0 4337 y Fi(7)81 b Fj(Read)33 b(a)h(rectangular)g (subimage)f(\(or)h(the)g(whole)f(image\))h(from)f(the)h(FITS)f(data)h (arra)m(y)-8 b(.)52 b(The)33 b(fpixel)f(and)227 4450 y(lpixel)27 b(arra)m(ys)j(giv)m(e)g(the)g(co)s(ordinates)f(of)g(the)h (\014rst)f(\(lo)m(w)m(er)h(left)f(corner\))h(and)f(last)g(\(upp)s(er)f (righ)m(t)h(corner\))227 4563 y(pixels)c(to)j(b)s(e)e(read)h(from)g (the)g(FITS)f(image.)40 b(Unde\014ned)25 b(FITS)h(arra)m(y)i(elemen)m (ts)f(will)d(b)s(e)i(returned)g(with)227 4675 y(a)k(v)-5 b(alue)29 b(=)f(*n)m(ullv)-5 b(al,)28 b(\(note)i(that)g(this)e (parameter)i(giv)m(es)f(the)h(address)e(of)h(the)h(n)m(ull)d(v)-5 b(alue,)29 b(not)h(the)f(n)m(ull)227 4788 y(v)-5 b(alue)35 b(itself)7 b(\))35 b(unless)f(n)m(ulv)-5 b(al)34 b(=)i(0)g(or)f(*n)m (ulv)-5 b(al)35 b(=)g(0,)j(in)c(whic)m(h)g(case)j(no)f(c)m(hec)m(ks)h (for)e(unde\014ned)f(pixels)227 4901 y(will)28 b(b)s(e)i(p)s(erformed.) 95 5138 y Fe(int)47 b(fits_read_subset)d(/)j(ffgsv)286 5251 y(\(fitsfile)f(*fptr,)g(int)94 b(datatype,)46 b(long)g(*fpixel,)g (long)g(*lpixel,)g(long)h(*inc,)334 5364 y(DTYPE)f(*nulval,)g(>)h (DTYPE)g(*array,)f(int)h(*anynul,)e(int)i(*status\))0 5601 y Fi(8)81 b Fj(Read)32 b(pixels)f(from)h(the)g(FITS)g(data)h(arra) m(y)-8 b(.)48 b('fpixel')31 b(is)h(the)g(starting)g(pixel)f(lo)s (cation)h(and)g(is)g(an)g(arra)m(y)h(of)227 5714 y(length)g(NAXIS)g (suc)m(h)g(that)h(fpixel[0])e(is)g(in)g(the)i(range)f(1)h(to)g(NAXIS1,) g(fpixel[1])e(is)h(in)f(the)h(range)h(1)f(to)p eop %%Page: 42 50 42 49 bop 0 299 a Fj(42)1379 b Fh(CHAPTER)30 b(5.)71 b(BASIC)30 b(CFITSIO)f(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)227 555 y Fj(NAXIS2,)f(etc.)41 b(The)28 b(nelemen)m(ts)g(parameter)g(sp)s (eci\014es)f(the)h(n)m(um)m(b)s(er)f(of)h(pixels)f(to)i(read.)39 b(If)28 b(fpixel)e(is)h(set)227 668 y(to)36 b(the)f(\014rst)f(pixel,)h (and)g(nelemen)m(ts)f(is)g(set)i(equal)f(to)g(the)g(NAXIS1)h(v)-5 b(alue,)36 b(then)e(this)g(routine)g(w)m(ould)227 781 y(read)28 b(the)g(\014rst)f(ro)m(w)h(of)g(the)h(image.)40 b(Alternativ)m(ely)-8 b(,)28 b(if)f(nelemen)m(ts)h(is)f(set)h(equal)g (to)g(NAXIS1)g(*)h(NAXIS2)227 894 y(then)h(it)g(w)m(ould)f(read)i(an)f (en)m(tire)g(2D)h(image,)g(or)g(the)f(\014rst)g(plane)f(of)i(a)g(3-D)g (datacub)s(e.)227 1063 y(The)39 b(\014rst)f(routine)g(will)f(return)g (an)m(y)j(unde\014ned)d(pixels)g(in)h(the)h(FITS)f(arra)m(y)i(equal)e (to)i(the)f(v)-5 b(alue)39 b(of)227 1176 y(*n)m(ullv)-5 b(al)41 b(\(note)i(that)g(this)e(parameter)i(giv)m(es)g(the)f(address)g (of)g(the)h(n)m(ull)d(v)-5 b(alue,)45 b(not)e(the)f(n)m(ull)e(v)-5 b(alue)227 1289 y(itself)7 b(\))39 b(unless)f(n)m(ulv)-5 b(al)37 b(=)i(0)h(or)f(*n)m(ulv)-5 b(al)38 b(=)h(0,)j(in)c(whic)m(h)g (case)j(no)e(c)m(hec)m(ks)i(for)e(unde\014ned)e(pixels)h(will)227 1402 y(b)s(e)c(p)s(erformed.)51 b(The)34 b(second)g(routine)g(is)f (similar)f(except)j(that)g(an)m(y)g(unde\014ned)d(pixels)g(will)g(ha)m (v)m(e)k(the)227 1515 y(corresp)s(onding)29 b(n)m(ullarra)m(y)f(elemen) m(t)j(set)g(equal)f(to)h(TR)m(UE)g(\(=)f(1\).)95 1813 y Fe(int)47 b(fits_read_pix)e(/)i(ffgpxv)286 1926 y(\(fitsfile)f (*fptr,)g(int)94 b(datatype,)46 b(long)g(*fpixel,)g(long)g(nelements,) 334 2039 y(DTYPE)g(*nulval,)g(>)h(DTYPE)g(*array,)f(int)h(*anynul,)e (int)i(*status\))95 2265 y(int)g(fits_read_pixnull)c(/)48 b(ffgpxf)286 2378 y(\(fitsfile)e(*fptr,)g(int)94 b(datatype,)46 b(long)g(*fpixel,)g(long)g(nelements,)334 2491 y(>)i(DTYPE)e(*array,)g (char)g(*nullarray,)f(int)i(*anynul,)f(int)g(*status\))0 2869 y Ff(5.6)135 b(Image)46 b(Compression)0 3129 y Fj(CFITSIO)29 b(no)m(w)h(transparen)m(tly)g(supp)s(orts)e(2)j(t)m(yp)s(es)f(of)h (image)g(compression:)0 3289 y(1\))j(The)f(en)m(tire)h(FITS)e(\014le)h (ma)m(y)h(b)s(e)f(externally)g(compressed)g(with)f(the)i(gzip)f(or)g (Unix)f(compress)i(algorithm,)0 3402 y(pro)s(ducing)22 b(a)j(*.gz)h(or)f(*.Z)g(\014le,)g(resp)s(ectiv)m(ely)-8 b(.)38 b(When)25 b(reading)e(compressed)i(\014les)e(of)i(this)e(t)m(yp) s(e,)k(CFITSIO)c(\014rst)0 3515 y(uncompresses)j(the)i(en)m(tire)f (\014le)f(in)m(to)h(memory)g(b)s(efore)g(p)s(erforming)e(the)i (requested)g(read)g(op)s(erations.)39 b(Output)0 3628 y(\014les)30 b(can)h(b)s(e)f(directly)f(written)h(in)f(the)i(gzip)f (compressed)g(format)h(if)f(the)h(user-sp)s(eci\014ed)d(\014lename)i (ends)g(with)0 3741 y(`.gz'.)42 b(In)29 b(this)f(case,)j(CFITSIO)d (initially)e(writes)j(the)h(uncompressed)e(\014le)h(in)f(memory)i(and)f (then)g(compresses)0 3853 y(it)k(and)f(writes)g(it)h(to)g(disk)f(when)g (the)h(FITS)f(\014le)h(is)f(closed,)h(th)m(us)g(sa)m(ving)g(user)f (disk)g(space.)49 b(Read)33 b(and)g(write)0 3966 y(access)c(to)g(these) f(compressed)f(FITS)g(\014les)g(is)g(generally)g(quite)g(fast;)i(the)f (main)e(limitation)g(is)h(that)h(there)g(m)m(ust)0 4079 y(b)s(e)i(enough)g(a)m(v)-5 b(ailable)30 b(memory)g(\(or)h(sw)m(ap)f (space\))h(to)g(hold)e(the)i(en)m(tire)f(uncompressed)f(FITS)h(\014le.) 0 4239 y(2\))36 b(CFITSIO)d(also)i(supp)s(orts)e(a)i(new)m(er)g(image)h (compression)e(format)h(in)f(whic)m(h)f(the)i(image)h(is)e(divided)e (in)m(to)0 4352 y(a)43 b(grid)e(of)h(rectangular)g(tiles,)j(and)c(eac)m (h)j(tile)d(of)i(pixels)d(is)i(individually)36 b(compressed.)76 b(The)42 b(compressed)0 4465 y(tiles)36 b(are)h(stored)g(in)e(ro)m(ws)i (of)f(a)i(v)-5 b(ariable)35 b(length)h(arra)m(y)h(column)f(in)f(a)i (FITS)f(binary)f(table,)j(but)e(CFITSIO)0 4578 y(recognizes)31 b(that)f(the)g(binary)f(table)g(extension)h(con)m(tains)g(an)g(image)g (and)g(treats)h(it)e(as)h(if)f(it)h(w)m(ere)g(an)g(IMA)m(GE)0 4691 y(extension.)46 b(This)31 b(tile-compressed)g(format)i(is)e(esp)s (ecially)g(w)m(ell)g(suited)g(for)h(compressing)g(v)m(ery)g(large)h (images)0 4804 y(b)s(ecause)e(a\))h(the)g(FITS)e(header)h(k)m(eyw)m (ords)h(remain)e(uncompressed)g(for)h(rapid)e(read)i(access,)i(and)e(b) s(ecause)g(b\))0 4917 y(it)j(is)g(p)s(ossible)e(to)j(extract)i(and)d (uncompress)f(sections)i(of)f(the)h(image)g(without)f(ha)m(ving)g(to)h (uncompress)f(the)0 5030 y(en)m(tire)e(image.)45 b(This)30 b(format)j(is)e(also)g(m)m(uc)m(h)h(more)g(e\013ectiv)m(e)i(in)d (compressing)f(\015oating)i(p)s(oin)m(t)f(images)h(\(using)0 5143 y(a)f(lossy)e(compression)h(algorithm\))g(than)g(simply)e (compressing)h(the)i(image)f(using)f(gzip)h(or)g(compress.)0 5303 y(A)g(detailed)g(description)e(of)j(this)e(format)i(is)e(a)m(v)-5 b(ailable)30 b(at:)0 5601 y Fe(http://heasarc.gsfc.nasa)o(.gov)o(/doc)o (s/s)o(oftw)o(are/)o(fit)o(sio/)334 5714 y(compression/compress_imag)o (e.h)o(tml)p eop %%Page: 43 51 43 50 bop 0 299 a Fh(5.6.)72 b(IMA)m(GE)31 b(COMPRESSION)2567 b Fj(43)0 555 y(The)36 b(N-dimensional)f(FITS)h(image)h(can)g(b)s(e)g (divided)d(in)m(to)j(an)m(y)g(desired)e(rectangular)i(grid)f(of)h (compression)0 668 y(tiles.)75 b(By)43 b(default)e(the)i(tiles)e(are)h (c)m(hosen)h(to)g(corresp)s(ond)e(to)i(the)f(ro)m(ws)h(of)f(the)g (image,)k(eac)m(h)d(con)m(taining)0 781 y(NAXIS1)36 b(pixels.)56 b(F)-8 b(or)36 b(example,)h(a)g(800)g(x)f(800)h(x)f(4)g(pixel)e(data)j (cub)s(e)e(w)m(ould)g(b)s(e)g(divided)e(in)i(to)h(3200)i(tiles)0 894 y(con)m(taining)30 b(800)h(pixels)d(eac)m(h)k(b)m(y)e(default.)40 b(Alternativ)m(ely)-8 b(,)30 b(this)f(data)i(cub)s(e)e(could)g(b)s(e)h (divided)d(in)m(to)j(256)i(tiles)0 1007 y(that)c(are)g(eac)m(h)g(100)h (X)e(100)i(X)e(1)h(pixels)d(in)h(size,)i(or)f(4)h(tiles)e(con)m (taining)h(800)i(x)e(800)h(X)g(1)g(pixels,)e(or)h(a)h(single)e(tile)0 1120 y(con)m(taining)j(the)h(en)m(tire)f(data)h(cub)s(e.)40 b(Note)31 b(that)f(the)f(image)h(dimensions)d(are)j(not)f(required)f (to)i(b)s(e)f(an)h(in)m(teger)0 1233 y(m)m(ultiple)j(of)j(the)g(tile)e (dimensions,)h(so,)i(for)e(example,)i(this)e(data)h(cub)s(e)f(could)f (also)i(b)s(e)f(divided)d(in)m(to)k(250)h(X)0 1346 y(200)32 b(pixel)c(tiles,)i(in)f(whic)m(h)g(case)j(the)e(last)g(tile)g(in)f(eac) m(h)j(ro)m(w)e(w)m(ould)f(only)h(con)m(tain)g(50)i(X)e(200)i(pixels.)0 1506 y(Curren)m(tly)-8 b(,)29 b(3)i(image)f(compression)g(algorithms)f (are)h(supp)s(orted:)39 b(Rice,)31 b(GZIP)-8 b(,)30 b(and)g(PLIO.)g (Rice)g(and)f(GZIP)0 1619 y(are)34 b(general)f(purp)s(ose)f(algorithms) g(that)i(can)g(b)s(e)f(used)g(to)h(compress)f(almost)h(an)m(y)f(image.) 51 b(The)32 b(PLIO)h(algo-)0 1732 y(rithm,)38 b(on)f(the)g(other)h (hand,)g(is)e(more)i(sp)s(ecialized)d(and)i(w)m(as)h(dev)m(elop)s(ed)e (for)h(use)g(in)f(IRAF)i(to)g(store)g(pixel)0 1844 y(data)31 b(qualit)m(y)f(masks.)41 b(It)30 b(is)g(designed)f(to)i(only)f(w)m(ork) g(on)h(images)f(con)m(taining)g(p)s(ositiv)m(e)g(in)m(tegers)g(with)g (v)-5 b(alues)0 1957 y(up)29 b(to)i(ab)s(out)g(2**24.)42 b(Other)30 b(image)h(compression)e(algorithms)h(ma)m(y)h(b)s(e)e(supp)s (orted)g(in)g(the)h(future.)0 2118 y(The)41 b(3)g(supp)s(orted)f(image) h(compression)f(algorithms)g(are)i(all)e('loss-less')h(when)f(applied)f (to)j(in)m(teger)g(FITS)0 2230 y(images;)34 b(the)f(pixel)e(v)-5 b(alues)31 b(are)i(preserv)m(ed)g(exactly)g(with)e(no)i(loss)e(of)i (information)e(during)f(the)j(compression)0 2343 y(and)i(uncompression) f(pro)s(cess.)57 b(Floating)36 b(p)s(oin)m(t)f(FITS)g(images)h(\(whic)m (h)f(ha)m(v)m(e)i(BITPIX)f(=)f(-32)i(or)f(-64\))i(are)0 2456 y(\014rst)33 b(quan)m(tized)h(in)m(to)g(scaled)g(in)m(teger)h (pixel)d(v)-5 b(alues)33 b(b)s(efore)h(b)s(eing)f(compressed.)51 b(This)32 b(tec)m(hnique)i(pro)s(duces)0 2569 y(m)m(uc)m(h)27 b(higher)e(compression)h(factors)h(than)g(simply)d(using)h(GZIP)h(to)i (compress)e(the)h(image,)h(but)e(it)g(also)h(means)0 2682 y(that)46 b(the)f(original)f(\015oating)h(v)-5 b(alue)45 b(pixel)e(v)-5 b(alues)45 b(ma)m(y)h(not)f(b)s(e)g(precisely)f (returned)g(when)g(the)h(image)h(is)0 2795 y(uncompressed.)55 b(When)35 b(done)h(prop)s(erly)-8 b(,)35 b(this)g(only)f(discards)g (the)i('noise')g(from)f(the)h(\015oating)f(p)s(oin)m(t)g(v)-5 b(alues)0 2908 y(without)25 b(losing)h(an)m(y)g(signi\014can)m(t)g (information.)37 b(The)26 b(amoun)m(t)h(of)g(noise)f(that)h(is)e (discarded)g(can)i(b)s(e)e(con)m(trolled)0 3021 y(b)m(y)30 b(the)h('noise)p 511 3021 28 4 v 32 w(bits')f(compression)f(parameter.) 0 3181 y(No)42 b(sp)s(ecial)e(action)i(is)e(required)g(to)i(read)g (tile-compressed)e(images)i(b)s(ecause)f(all)g(the)g(CFITSIO)f (routines)0 3294 y(that)33 b(read)g(normal)f(uncompressed)g(FITS)g (images)h(can)g(also)g(read)g(images)g(in)e(the)i(tile-compressed)f (format;)0 3407 y(CFITSIO)39 b(essen)m(tially)h(treats)h(the)g(binary)e (table)h(that)i(con)m(tains)f(the)f(compressed)h(tiles)e(as)i(if)f(it)g (w)m(ere)h(an)0 3520 y(IMA)m(GE)31 b(extension.)0 3680 y(When)d(creating)h(\(writing\))f(a)h(new)f(image)h(with)e(CFITSIO,)h (a)h(normal)e(uncompressed)h(FITS)g(primary)e(arra)m(y)0 3793 y(or)k(IMA)m(GE)h(extension)f(will)d(b)s(e)i(written)h(unless)e (the)i(tile-compressed)f(format)i(has)f(b)s(een)f(sp)s(eci\014ed)f(in)h (1)h(of)h(2)0 3906 y(p)s(ossible)d(w)m(a)m(ys:)0 4066 y(1\))d(A)m(t)g(run)d(time,)j(when)e(sp)s(ecifying)f(the)i(name)g(of)g (the)g(output)g(FITS)f(\014le)g(to)i(b)s(e)e(created)i(at)g(run)d (time,)j(the)g(user)0 4179 y(can)j(indicate)g(that)g(images)h(should)d (b)s(e)h(written)h(in)e(tile-compressed)i(format)g(b)m(y)g(enclosing)g (the)g(compression)0 4292 y(parameters)23 b(in)e(square)h(brac)m(k)m (ets)i(follo)m(wing)d(the)h(ro)s(ot)h(disk)e(\014le)g(name.)39 b(The)21 b(`imcop)m(y')i(example)f(program)g(that)0 4405 y(included)30 b(with)i(the)i(CFITSIO)d(distribution)f(can)j(b)s(e)g (used)f(for)h(this)g(purp)s(ose)e(to)j(compress)f(or)g(uncompress)0 4517 y(images.)58 b(Here)36 b(are)h(some)f(examples)g(of)g(the)g (extended)g(\014le)f(name)h(syn)m(tax)h(for)f(sp)s(ecifying)e (tile-compressed)0 4630 y(output)c(images:)191 4924 y Fe(myfile.fit[compress])185 b(-)48 b(use)f(the)g(default)e(compression) g(algorithm)g(\(Rice\))1432 5036 y(and)i(the)g(default)e(tile)i(size)g (\(row)f(by)i(row\))191 5262 y(myfile.fit[compress)42 b(GZIP])47 b(-)g(use)g(the)g(specified)e(compression)g(algorithm;)191 5375 y(myfile.fit[compress)d(Rice])238 b(only)46 b(the)h(first)g (letter)f(of)h(the)g(algorithm)191 5488 y(myfile.fit[compress)42 b(PLIO])238 b(name)46 b(is)i(required.)191 5714 y(myfile.fit[compress) 42 b(R)48 b(100,100])141 b(-)47 b(use)g(Rice)g(compression)e(and)p eop %%Page: 44 52 44 51 bop 0 299 a Fj(44)1379 b Fh(CHAPTER)30 b(5.)71 b(BASIC)30 b(CFITSIO)f(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)1861 555 y Fe(100)47 b(x)h(100)f(pixel)f(tile)h(size)191 781 y(myfile.fit[compress)42 b(R)48 b(100,100;2])d(-)i(as)h(above,)e(and)h (also)f(use)h(noisebits)e(=)j(2)0 1031 y Fj(2\))29 b(Before)g(calling)d (the)i(CFITSIO)e(routine)h(to)i(write)e(the)h(image)g(header)g(k)m(eyw) m(ords)g(\(e.g.,)j(\014ts)p 3335 1031 28 4 v 32 w(create)p 3603 1031 V 34 w(image\))0 1144 y(the)37 b(programmer)g(can)g(call)g (the)g(routines)f(describ)s(ed)f(b)s(elo)m(w)h(to)i(sp)s(ecify)e(the)h (compression)f(algorithm)h(and)0 1257 y(the)d(tiling)e(pattern)i(that)h (is)e(to)i(b)s(e)e(used.)51 b(There)34 b(are)h(3)f(routines)f(for)h(sp) s(ecifying)e(the)i(v)-5 b(arious)33 b(compression)0 1370 y(parameters)e(and)e(3)i(corresp)s(onding)e(routines)g(to)i(return)e (the)i(curren)m(t)f(v)-5 b(alues)30 b(of)g(the)h(parameters:)95 1619 y Fe(int)47 b(fits_set_compression_type\()o(fit)o(sfil)o(e)42 b(*fptr,)k(int)h(comptype,)e(int)i(*status\))95 1732 y(int)g(fits_set_tile_dim\(fitsfile)41 b(*fptr,)46 b(int)h(ndim,)f (long)h(*tilesize,)e(int)i(*status\))95 1845 y(int)g (fits_set_noise_bits\(fitsfi)o(le)41 b(*fptr,)47 b(int)f(noisebits,)f (int)i(*status\))95 2071 y(int)g(fits_get_compression_type\()o(fit)o (sfil)o(e)42 b(*fptr,)k(int)h(*comptype,)e(int)i(*status\))95 2184 y(int)g(fits_get_tile_dim\(fitsfile)41 b(*fptr,)46 b(int)h(ndim,)f(long)h(*tilesize,)e(int)i(*status\))95 2297 y(int)g(fits_get_noise_bits\(fitsfi)o(le)41 b(*fptr,)47 b(int)f(*noisebits,)f(int)i(*status\))0 2547 y Fj(3)24 b(sym)m(b)s(olic)d(constan)m(ts)k(are)e(de\014ned)f(for)h(use)g(as)g (the)h(v)-5 b(alue)22 b(of)i(the)f(`compt)m(yp)s(e')h(parameter:)38 b(GZIP)p 3447 2547 V 32 w(1,)25 b(RICE)p 3802 2547 V 32 w(1,)0 2660 y(or)i(PLIO)p 336 2660 V 32 w(1.)39 b(En)m(tering)26 b(NULL)h(for)f(compt)m(yp)s(e)h(will)d(turn)i(o\013)h(the)g (tile-compression)e(and)h(cause)h(normal)f(FITS)0 2773 y(images)k(to)i(b)s(e)d(written.)0 2933 y(The)h('noisebits')g (parameter)i(is)e(only)g(used)g(when)g(compressing)g(\015oating)h(p)s (oin)m(t)f(images.)43 b(The)30 b(default)g(v)-5 b(alue)0 3046 y(is)24 b(4.)40 b(Decreasing)25 b(the)h(v)-5 b(alue)24 b(of)h(noisebits)f(will)e(impro)m(v)m(e)j(the)h(o)m(v)m(erall)f (compression)f(e\016ciency)h(at)h(the)f(exp)s(ense)0 3159 y(of)31 b(losing)e(more)h(information.)0 3319 y(A)g(small)e (example)h(program)g(called)g('imcop)m(y')g(is)g(included)e(with)h (CFITSIO)g(that)i(can)f(b)s(e)g(used)g(to)h(compress)0 3432 y(\(or)44 b(uncompress\))g(an)m(y)g(FITS)g(image.)82 b(This)42 b(program)i(can)h(b)s(e)e(used)h(to)g(exp)s(erimen)m(t)g (with)f(the)h(v)-5 b(arious)0 3545 y(compression)29 b(options)h(on)g (existing)g(FITS)f(images)i(as)f(sho)m(wn)g(in)f(these)i(examples:)0 3794 y Fe(1\))95 b(imcopy)46 b(infile.fit)f('outfile.fit[compress]')334 4020 y(This)i(will)f(use)h(the)g(default)f(compression)f(algorithm)g (\(Rice\))h(and)h(the)334 4133 y(default)f(tile)h(size)f(\(row)h(by)g (row\))0 4359 y(2\))95 b(imcopy)46 b(infile.fit)f ('outfile.fit[compress)d(GZIP]')334 4585 y(This)47 b(will)f(use)h(the)g (GZIP)g(compression)e(algorithm)g(and)i(the)g(default)334 4698 y(tile)g(size)f(\(row)h(by)g(row\).)94 b(The)47 b(allowed)f(compression)f(algorithms)g(are)334 4811 y(Rice,)h(GZIP,)h (and)g(PLIO.)94 b(Only)46 b(the)h(first)g(letter)f(of)h(the)g (algorithm)334 4924 y(name)g(needs)f(to)h(be)g(specified.)0 5149 y(3\))95 b(imcopy)46 b(infile.fit)f('outfile.fit[compress)d(G)47 b(100,100]')334 5375 y(This)g(will)f(use)h(the)g(GZIP)g(compression)e (algorithm)g(and)i(100)g(X)g(100)g(pixel)334 5488 y(tiles.)0 5714 y(4\))95 b(imcopy)46 b(infile.fit)f('outfile.fit[compress)d(R)47 b(100,100;)f(4]')p eop %%Page: 45 53 45 52 bop 0 299 a Fh(5.7.)72 b(ASCI)s(I)29 b(AND)i(BINAR)-8 b(Y)31 b(T)-8 b(ABLE)31 b(R)m(OUTINES)1864 b Fj(45)334 668 y Fe(This)47 b(will)f(use)h(the)g(Rice)g(compression)e(algorithm,)g (100)h(X)i(100)f(pixel)334 781 y(tiles,)f(and)h(noise_bits)e(=)j(4)f (\(assuming)e(the)i(input)g(image)f(has)h(a)334 894 y(floating)f(point) g(data)h(type\).)93 b(Decreasing)45 b(the)i(value)g(of)g(noisebits)334 1007 y(will)g(improve)f(the)g(overall)g(compression)f(efficiency)g(at)i (the)g(expense)334 1120 y(of)g(losing)f(more)h(information.)0 1346 y(5\))95 b(imcopy)46 b(infile.fit)f(outfile.fit)334 1571 y(If)i(the)g(input)g(file)f(is)h(in)h(tile-compressed)43 b(format,)j(then)h(it)g(will)f(be)334 1684 y(uncompressed)f(to)i(the)g (output)f(file.)94 b(Otherwise,)45 b(it)i(simply)f(copies)334 1797 y(the)h(input)f(image)h(to)g(the)g(output)f(image.)0 2023 y(6\))95 b(imcopy)46 b('infile.fit[1001:1500,20)o(01:2)o(500])o(') 89 b(outfile.fit)334 2249 y(This)47 b(extracts)e(a)j(500)f(X)g(500)g (pixel)f(section)g(of)h(the)g(much)g(larger)334 2362 y(input)f(image)h(\(which)f(may)h(be)g(in)g(tile-compressed)d (format\).)93 b(The)334 2475 y(output)46 b(is)h(a)h(normal)e (uncompressed)e(FITS)j(image.)0 2700 y(7\))95 b(imcopy)46 b('infile.fit[1001:1500,20)o(01:2)o(500])o(')89 b(outfile.fit.gz)334 2926 y(Same)47 b(as)g(above,)f(except)g(the)h(output)f(file)h(is)g (externally)e(compressed)334 3039 y(using)h(the)h(gzip)g(algorithm.)0 3513 y Ff(5.7)135 b(ASCI)t(I)45 b(and)f(Binary)h(T)-11 b(able)45 b(Routines)0 3768 y Fj(These)36 b(routines)f(p)s(erform)g (read)i(and)e(write)h(op)s(erations)g(on)g(columns)f(of)i(data)g(in)e (FITS)h(ASCI)s(I)e(or)j(Binary)0 3881 y(tables.)46 b(Note)33 b(that)g(in)d(the)j(follo)m(wing)d(discussions,)g(the)i(\014rst)g(ro)m (w)g(and)f(column)g(in)g(a)h(table)g(is)g(at)g(p)s(osition)f(1)0 3994 y(not)g(0.)0 4154 y(Users)k(should)f(also)i(read)f(the)h(follo)m (wing)e(c)m(hapter)j(on)e(the)h(CFITSIO)e(iterator)i(function)f(whic)m (h)f(pro)m(vides)h(a)0 4267 y(more)j(`ob)5 b(ject)39 b(orien)m(ted')f(metho)s(d)g(of)g(reading)f(and)h(writing)e(table)i (columns.)62 b(The)37 b(iterator)i(function)d(is)i(a)0 4380 y(little)c(more)i(complicated)f(to)h(use,)h(but)e(the)g(adv)-5 b(an)m(tages)38 b(are)d(that)i(it)e(usually)e(tak)m(es)k(less)d(co)s (de)i(to)g(p)s(erform)0 4493 y(the)e(same)h(op)s(eration,)f(and)f(the)i (resulting)d(program)h(oftens)i(runs)d(faster)i(b)s(ecause)g(the)h (FITS)e(\014les)g(are)h(read)0 4606 y(and)c(written)f(using)g(the)i (most)f(e\016cien)m(t)h(blo)s(c)m(k)f(size.)0 4924 y Fd(5.7.1)112 b(Create)38 b(New)f(T)-9 b(able)0 5149 y Fi(1)81 b Fj(Create)40 b(a)f(new)g(ASCI)s(I)e(or)i(bin)m(table)f(table) h(extension.)67 b(If)39 b(the)g(FITS)g(\014le)f(is)g(curren)m(tly)g (empt)m(y)i(then)f(a)227 5262 y(dumm)m(y)25 b(primary)e(arra)m(y)j (will)d(b)s(e)i(created)i(b)s(efore)e(app)s(ending)e(the)j(table)f (extension)h(to)g(it.)39 b(The)25 b(tblt)m(yp)s(e)227 5375 y(parameter)39 b(de\014nes)e(the)h(t)m(yp)s(e)h(of)f(table)g(and)f (can)i(ha)m(v)m(e)g(v)-5 b(alues)38 b(of)g(ASCI)s(I)p 2924 5375 28 4 v 31 w(TBL)g(or)g(BINAR)-8 b(Y)p 3659 5375 V 34 w(TBL.)227 5488 y(The)29 b(naxis2)f(parameter)i(giv)m(es)f (the)h(initial)c(n)m(um)m(b)s(er)i(of)h(ro)m(ws)g(to)h(b)s(e)f(created) h(in)e(the)h(table,)g(and)g(should)227 5601 y(normally)f(b)s(e)h(set)h (=)g(0.)40 b(CFITSIO)29 b(will)e(automatically)i(increase)h(the)f(size) h(of)g(the)g(table)f(as)h(additional)227 5714 y(ro)m(ws)d(are)g (written.)39 b(A)27 b(non-zero)g(n)m(um)m(b)s(er)f(of)h(ro)m(ws)g(ma)m (y)g(b)s(e)f(sp)s(eci\014ed)f(to)j(reserv)m(e)f(space)h(for)e(that)i (man)m(y)p eop %%Page: 46 54 46 53 bop 0 299 a Fj(46)1379 b Fh(CHAPTER)30 b(5.)71 b(BASIC)30 b(CFITSIO)f(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)227 555 y Fj(ro)m(ws,)41 b(ev)m(en)e(if)f(a)h(few)m(er)g(n)m(um)m(b)s(er)e (of)i(ro)m(ws)f(will)e(b)s(e)i(written.)65 b(The)38 b(tunit)f(and)h (extname)i(parameters)227 668 y(are)e(optional)e(and)h(a)h(n)m(ull)d(p) s(oin)m(ter)h(ma)m(y)i(b)s(e)f(giv)m(en)g(if)g(they)g(are)h(not)f (de\014ned.)61 b(The)37 b(FITS)f(Standard)227 781 y(recommends)29 b(that)h(only)f(letters,)h(digits,)f(and)g(the)g(underscore)g(c)m (haracter)i(b)s(e)e(used)g(in)f(column)g(names)227 894 y(\(the)d(tt)m(yp)s(e)g(parameter\))g(with)d(no)i(em)m(b)s(edded)f (spaces.)40 b(T)-8 b(railing)21 b(blank)i(c)m(haracters)j(are)e(not)h (signi\014can)m(t.)227 1007 y(It)36 b(is)f(recommended)g(that)i(all)e (the)h(column)e(names)i(in)e(a)j(giv)m(en)e(table)h(b)s(e)f(unique)f (within)f(the)j(\014rst)g(8)227 1120 y(c)m(haracters,)25 b(and)c(strongly)f(recommended)h(that)h(the)f(names)h(b)s(e)e(unique)g (within)e(the)k(\014rst)e(16)i(c)m(haracters.)95 1478 y Fe(int)47 b(fits_create_tbl)d(/)j(ffcrtb)286 1591 y(\(fitsfile)f (*fptr,)g(int)h(tbltype,)e(long)i(naxis2,)f(int)h(tfields,)e(char)i (*ttype[],)334 1704 y(char)g(*tform[],)e(char)i(*tunit[],)e(char)i (*extname,)e(int)i(*status\))0 1992 y Fd(5.7.2)112 b(Column)37 b(Information)f(Routines)0 2199 y Fi(1)81 b Fj(Get)30 b(the)g(n)m(um)m(b)s(er)e(of)i(ro)m(ws)g(or)f(columns)f(in)h(the)h (curren)m(t)f(FITS)g(table.)40 b(The)29 b(n)m(um)m(b)s(er)f(of)i(ro)m (ws)g(is)e(giv)m(en)i(b)m(y)227 2312 y(the)k(NAXIS2)f(k)m(eyw)m(ord)h (and)e(the)i(n)m(um)m(b)s(er)e(of)h(columns)f(is)g(giv)m(en)h(b)m(y)g (the)h(TFIELDS)e(k)m(eyw)m(ord)i(in)e(the)227 2424 y(header)e(of)h(the) g(table.)95 2670 y Fe(int)47 b(fits_get_num_rows)c(/)48 b(ffgnrw)286 2783 y(\(fitsfile)e(*fptr,)g(>)h(long)g(*nrows,)f(int)h (*status\);)95 3008 y(int)g(fits_get_num_cols)c(/)48 b(ffgncl)286 3121 y(\(fitsfile)e(*fptr,)g(>)h(int)g(*ncols,)f(int)h (*status\);)0 3366 y Fi(2)81 b Fj(Get)25 b(the)f(table)h(column)e(n)m (um)m(b)s(er)g(\(and)h(name\))h(of)f(the)h(column)e(whose)h(name)g (matc)m(hes)i(an)e(input)f(template)227 3479 y(name.)48 b(If)32 b(casesen)i(=)e(CASESEN)g(then)g(the)h(column)e(name)i(matc)m (h)h(will)c(b)s(e)i(case-sensitiv)m(e,)i(whereas)227 3592 y(if)26 b(casesen)i(=)e(CASEINSEN)g(then)h(the)g(case)h(will)c(b)s (e)i(ignored.)39 b(As)27 b(a)g(general)g(rule,)f(the)h(column)f(names) 227 3705 y(should)j(b)s(e)g(treated)j(as)e(case)i(INsensitiv)m(e.)227 3853 y(The)26 b(input)f(column)g(name)h(template)h(ma)m(y)g(b)s(e)f (either)g(the)h(exact)h(name)e(of)h(the)f(column)f(to)j(b)s(e)d(searc)m (hed)227 3966 y(for,)k(or)f(it)g(ma)m(y)h(con)m(tain)g(wild)d(card)i(c) m(haracters)i(\(*,)g(?,)f(or)f(#\),)h(or)f(it)g(ma)m(y)h(con)m(tain)g (the)f(in)m(teger)h(n)m(um)m(b)s(er)227 4079 y(of)k(the)f(desired)e (column)h(\(with)g(the)i(\014rst)e(column)g(=)h(1\).)46 b(The)32 b(`*')h(wild)d(card)i(c)m(haracter)h(matc)m(hes)h(an)m(y)227 4192 y(sequence)h(of)g(c)m(haracters)h(\(including)c(zero)j(c)m (haracters\))i(and)d(the)h(`?')53 b(c)m(haracter)36 b(matc)m(hes)g(an)m (y)f(single)227 4305 y(c)m(haracter.)42 b(The)29 b(#)h(wildcard)d(will) g(matc)m(h)k(an)m(y)e(consecutiv)m(e)i(string)e(of)g(decimal)g(digits)f (\(0-9\).)43 b(If)29 b(more)227 4418 y(than)43 b(one)f(column)g(name)g (in)f(the)i(table)g(matc)m(hes)g(the)g(template)g(string,)i(then)d(the) h(\014rst)e(matc)m(h)j(is)227 4530 y(returned)28 b(and)h(the)g(status)h (v)-5 b(alue)29 b(will)d(b)s(e)j(set)h(to)g(COL)p 2171 4530 28 4 v 32 w(NOT)p 2408 4530 V 32 w(UNIQUE)f(as)h(a)f(w)m(arning)f (that)i(a)g(unique)227 4643 y(matc)m(h)e(w)m(as)g(not)f(found.)39 b(T)-8 b(o)27 b(\014nd)f(the)h(other)g(cases)h(that)g(matc)m(h)g(the)g (template,)g(call)e(the)i(routine)e(again)227 4756 y(lea)m(ving)f(the)g (input)e(status)i(v)-5 b(alue)25 b(equal)f(to)i(COL)p 1950 4756 V 32 w(NOT)p 2187 4756 V 32 w(UNIQUE)f(and)f(the)h(next)h (matc)m(hing)f(name)g(will)227 4869 y(then)30 b(b)s(e)g(returned.)40 b(Rep)s(eat)30 b(this)g(pro)s(cess)g(un)m(til)e(a)j(status)g(=)f(COL)p 2628 4869 V 32 w(NOT)p 2865 4869 V 32 w(F)m(OUND)i(is)d(returned.)227 5017 y(The)36 b(FITS)g(Standard)g(recommends)g(that)i(only)d(letters,)k (digits,)e(and)f(the)h(underscore)f(c)m(haracter)j(b)s(e)227 5130 y(used)32 b(in)g(column)g(names)g(\(with)g(no)h(em)m(b)s(edded)f (spaces\).)49 b(T)-8 b(railing)30 b(blank)i(c)m(haracters)i(are)f(not)h (signif-)227 5243 y(ican)m(t.)57 b(It)36 b(is)f(recommended)g(that)h (all)f(the)h(column)e(names)i(in)e(a)i(giv)m(en)g(table)g(b)s(e)f (unique)f(within)f(the)227 5356 y(\014rst)i(8)i(c)m(haracters,)h(and)e (strongly)f(recommended)g(that)i(the)f(names)g(b)s(e)f(unique)f(within) f(the)j(\014rst)f(16)227 5469 y(c)m(haracters.)95 5714 y Fe(int)47 b(fits_get_colnum)d(/)j(ffgcno)p eop %%Page: 47 55 47 54 bop 0 299 a Fh(5.7.)72 b(ASCI)s(I)29 b(AND)i(BINAR)-8 b(Y)31 b(T)-8 b(ABLE)31 b(R)m(OUTINES)1864 b Fj(47)286 555 y Fe(\(fitsfile)46 b(*fptr,)g(int)h(casesen,)e(char)i(*templt,)e(>) j(int)f(*colnum,)334 668 y(int)g(*status\))95 894 y(int)g (fits_get_colname)d(/)j(ffgcnn)286 1007 y(\(fitsfile)f(*fptr,)g(int)h (casesen,)e(char)i(*templt,)e(>)j(char)e(*colname,)334 1120 y(int)h(*colnum,)f(int)g(*status\))0 1350 y Fi(3)81 b Fj(Return)30 b(the)i(data)g(t)m(yp)s(e,)h(v)m(ector)g(rep)s(eat)f(v) -5 b(alue,)31 b(and)g(the)h(width)e(in)g(b)m(ytes)i(of)g(a)g(column)e (in)g(an)i(ASCI)s(I)e(or)227 1463 y(binary)k(table.)55 b(Allo)m(w)m(ed)35 b(v)-5 b(alues)35 b(for)g(the)h(data)g(t)m(yp)s(e)f (in)f(ASCI)s(I)g(tables)h(are:)51 b(TSTRING,)35 b(TSHOR)-8 b(T,)227 1576 y(TLONG,)36 b(TFLO)m(A)-8 b(T,)36 b(and)f(TDOUBLE.)i (Binary)d(tables)i(also)g(supp)s(ort)e(these)i(t)m(yp)s(es:)52 b(TLOGICAL,)227 1689 y(TBIT,)38 b(TBYTE,)h(TCOMPLEX)e(and)h (TDBLCOMPLEX.)h(The)f(negativ)m(e)h(of)g(the)g(data)g(t)m(yp)s(e)g(co)s (de)227 1802 y(v)-5 b(alue)31 b(is)f(returned)g(if)g(it)g(is)h(a)g(v)-5 b(ariable)30 b(length)g(arra)m(y)i(column.)42 b(Note)32 b(that)g(in)d(the)j(case)g(of)f(a)g('J')h(32-bit)227 1914 y(in)m(teger)f(binary)d(table)i(column,)f(this)g(routine)g(will)e (return)i(data)i(t)m(yp)s(e)f(=)g(TINT32BIT)g(\(whic)m(h)f(in)g(fact) 227 2027 y(is)35 b(equiv)-5 b(alen)m(t)35 b(to)i(TLONG\).)f(With)f (most)h(curren)m(t)g(C)f(compilers,)h(a)h(v)-5 b(alue)35 b(in)f(a)j('J')f(column)e(has)i(the)227 2140 y(same)29 b(size)f(as)h(an)f('in)m(t')h(v)-5 b(ariable,)28 b(and)f(ma)m(y)j(not)e (b)s(e)g(equiv)-5 b(alen)m(t)28 b(to)h(a)g('long')f(v)-5 b(ariable,)28 b(whic)m(h)f(is)h(64-bits)227 2253 y(long)i(on)h(an)f (increasing)f(n)m(um)m(b)s(er)g(of)h(compilers.)227 2398 y(The)22 b('rep)s(eat')h(parameter)g(returns)f(the)g(v)m(ector)i(rep)s (eat)f(coun)m(t)g(on)f(the)h(binary)e(table)h(TF)m(ORMn)g(k)m(eyw)m (ord)227 2511 y(v)-5 b(alue.)59 b(\(ASCI)s(I)35 b(table)i(columns)e (alw)m(a)m(ys)i(ha)m(v)m(e)h(rep)s(eat)e(=)g(1\).)60 b(The)36 b('width')f(parameter)i(returns)f(the)227 2624 y(width)29 b(in)g(b)m(ytes)i(of)g(a)f(single)f(column)h(elemen)m(t)h (\(e.g.,)h(a)f('10D')h(binary)d(table)h(column)f(will)f(ha)m(v)m(e)k (width)227 2737 y(=)d(8,)i(an)e(ASCI)s(I)f(table)h('F12.2')j(column)d (will)e(ha)m(v)m(e)j(width)e(=)h(12,)i(and)e(a)h(binary)d(table'60A')k (c)m(haracter)227 2850 y(string)36 b(column)g(will)f(ha)m(v)m(e)j (width)e(=)h(60\);)42 b(Note)c(that)g(this)e(routine)h(supp)s(orts)e (the)i(lo)s(cal)g(con)m(v)m(en)m(tion)227 2963 y(for)42 b(sp)s(ecifying)d(arra)m(ys)k(of)f(\014xed)f(length)g(strings)f(within) g(a)i(binary)e(table)h(c)m(haracter)j(column)c(using)227 3076 y(the)h(syn)m(tax)g(TF)m(ORM)g(=)g('rAw')f(where)g('r')h(is)f(the) h(total)g(n)m(um)m(b)s(er)e(of)i(c)m(haracters)h(\(=)f(the)g(width)e (of)227 3189 y(the)g(column\))f(and)f('w')i(is)e(the)i(width)e(of)h(a)h (unit)e(string)g(within)f(the)j(column.)64 b(Th)m(us)37 b(if)g(the)i(column)227 3302 y(has)34 b(TF)m(ORM)h(=)f('60A12')j(then)d (this)f(means)h(that)h(eac)m(h)g(ro)m(w)g(of)f(the)h(table)f(con)m (tains)g(5)h(12-c)m(haracter)227 3415 y(substrings)22 b(within)g(the)i(60-c)m(haracter)j(\014eld,)e(and)e(th)m(us)h(in)f (this)g(case)i(this)f(routine)f(will)e(return)i(t)m(yp)s(eco)s(de)227 3528 y(=)36 b(TSTRING,)f(rep)s(eat)h(=)f(60,)j(and)d(width)f(=)i(12.)57 b(The)35 b(n)m(um)m(b)s(er)g(of)h(substings)e(in)g(an)m(y)i(binary)e (table)227 3640 y(c)m(haracter)i(string)d(\014eld)f(can)i(b)s(e)g (calculated)g(b)m(y)f(\(rep)s(eat/width\).)52 b(A)34 b(n)m(ull)d(p)s(oin)m(ter)i(ma)m(y)i(b)s(e)e(giv)m(en)h(for)227 3753 y(an)m(y)d(of)g(the)f(output)g(parameters)h(that)g(are)g(not)f (needed.)227 3899 y(The)46 b(second)g(routine,)j(\014t)p 1188 3899 28 4 v 33 w(get)p 1341 3899 V 34 w(eqcolt)m(yp)s(e)d(is)f (similar)f(except)j(that)f(in)f(the)h(case)i(of)e(scaled)g(in)m(teger) 227 4012 y(columns)34 b(it)g(returns)g(the)h('equiv)-5 b(alen)m(t')35 b(data)h(t)m(yp)s(e)f(that)h(is)e(needed)g(to)i(store)g (the)f(scaled)g(v)-5 b(alues,)36 b(and)227 4125 y(not)28 b(necessarily)f(the)h(ph)m(ysical)e(data)i(t)m(yp)s(e)g(of)g(the)g (unscaled)e(v)-5 b(alues)28 b(as)f(stored)h(in)f(the)g(FITS)g(table.)40 b(F)-8 b(or)227 4237 y(example)37 b(if)g(a)h('1I')g(column)e(in)g(a)i (binary)e(table)h(has)h(TSCALn)d(=)j(1)f(and)g(TZER)m(On)f(=)i(32768,)j (then)227 4350 y(this)28 b(column)f(e\013ectiv)m(ely)j(con)m(tains)e (unsigned)f(short)h(in)m(teger)h(v)-5 b(alues,)28 b(and)g(th)m(us)h (the)f(returned)g(v)-5 b(alue)28 b(of)227 4463 y(t)m(yp)s(eco)s(de)34 b(will)c(b)s(e)j(TUSHOR)-8 b(T,)32 b(not)h(TSHOR)-8 b(T.)33 b(Similarly)-8 b(,)30 b(if)i(a)i(column)e(has)g(TTYPEn)g(=)h('1I')h (and)227 4576 y(TSCALn)29 b(=)h(0.12,)i(then)e(the)h(returned)e(t)m(yp) s(eco)s(de)i(will)c(b)s(e)j(TFLO)m(A)-8 b(T.)95 4806 y Fe(int)47 b(fits_get_coltype)d(/)j(ffgtcl)286 4919 y(\(fitsfile)f(*fptr,)g(int)h(colnum,)e(>)j(int)f(*typecode,)e(long)h (*repeat,)334 5032 y(long)h(*width,)f(int)g(*status\))95 5258 y(int)h(fits_get_eqcoltype)c(/)48 b(ffeqty)286 5371 y(\(fitsfile)e(*fptr,)g(int)h(colnum,)e(>)j(int)f(*typecode,)e(long)h (*repeat,)334 5484 y(long)h(*width,)f(int)g(*status\))0 5714 y Fi(4)81 b Fj(Return)29 b(the)h(displa)m(y)e(width)g(of)i(a)h (column.)39 b(This)28 b(is)h(the)h(length)g(of)g(the)g(string)f(that)i (will)c(b)s(e)i(returned)g(b)m(y)p eop %%Page: 48 56 48 55 bop 0 299 a Fj(48)1379 b Fh(CHAPTER)30 b(5.)71 b(BASIC)30 b(CFITSIO)f(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)227 555 y Fj(the)k(\014ts)p 514 555 28 4 v 32 w(read)p 718 555 V 33 w(col)f(routine)f(when)g(reading)g(the)i(column)d(as)j(a)f (formatted)h(string.)48 b(The)32 b(displa)m(y)g(width)227 668 y(is)c(determined)g(b)m(y)h(the)g(TDISPn)f(k)m(eyw)m(ord,)i(if)e (presen)m(t,)i(otherwise)e(b)m(y)h(the)g(data)h(t)m(yp)s(e)f(of)h(the)f (column.)95 1039 y Fe(int)47 b(fits_get_col_display_width)41 b(/)47 b(ffgcdw)286 1152 y(\(fitsfile)f(*fptr,)g(int)h(colnum,)e(>)j (int)f(*dispwidth,)e(int)h(*status\))0 1410 y Fi(5)81 b Fj(Return)27 b(the)i(n)m(um)m(b)s(er)e(of)i(and)e(size)i(of)f(the)h (dimensions)d(of)i(a)h(table)f(column)g(in)f(a)h(binary)f(table.)40 b(Normally)227 1523 y(this)27 b(information)g(is)g(giv)m(en)h(b)m(y)g (the)h(TDIMn)f(k)m(eyw)m(ord,)h(but)e(if)h(this)f(k)m(eyw)m(ord)h(is)f (not)i(presen)m(t)f(then)g(this)227 1635 y(routine)i(returns)f(naxis)g (=)h(1)h(and)f(naxes[0])h(equal)f(to)h(the)g(rep)s(eat)f(coun)m(t)h(in) e(the)i(TF)m(ORM)g(k)m(eyw)m(ord.)95 1893 y Fe(int)47 b(fits_read_tdim)d(/)k(ffgtdm)286 2006 y(\(fitsfile)e(*fptr,)g(int)h (colnum,)e(int)i(maxdim,)f(>)i(int)f(*naxis,)334 2119 y(long)g(*naxes,)f(int)g(*status\))0 2377 y Fi(6)81 b Fj(Deco)s(de)33 b(the)g(input)e(TDIMn)i(k)m(eyw)m(ord)g(string)e (\(e.g.)50 b('\(100,200\)'\))37 b(and)32 b(return)g(the)h(n)m(um)m(b)s (er)e(of)i(and)f(size)227 2490 y(of)c(the)g(dimensions)d(of)j(a)g (binary)e(table)h(column.)39 b(If)27 b(the)h(input)e(tdimstr)g(c)m (haracter)j(string)e(is)g(n)m(ull,)f(then)227 2603 y(this)e(routine)f (returns)g(naxis)g(=)i(1)f(and)g(naxes[0])i(equal)d(to)j(the)e(rep)s (eat)h(coun)m(t)g(in)e(the)h(TF)m(ORM)h(k)m(eyw)m(ord.)227 2716 y(This)k(routine)g(is)h(called)f(b)m(y)h(\014ts)p 1350 2716 V 33 w(read)p 1555 2716 V 33 w(tdim.)95 2973 y Fe(int)47 b(fits_decode_tdim)d(/)j(ffdtdm)286 3086 y(\(fitsfile)f(*fptr,)g(char)g(*tdimstr,)g(int)h(colnum,)e(int)i (maxdim,)f(>)i(int)e(*naxis,)334 3199 y(long)h(*naxes,)f(int)g (*status\))0 3457 y Fi(7)81 b Fj(W)-8 b(rite)22 b(a)h(TDIMn)f(k)m(eyw)m (ord)h(whose)f(v)-5 b(alue)22 b(has)h(the)f(form)g('\(l,m,n...\)')39 b(where)22 b(l,)h(m,)h(n...)38 b(are)23 b(the)g(dimensions)227 3570 y(of)31 b(a)g(m)m(ultidimension)26 b(arra)m(y)31 b(column)e(in)g(a)i(binary)d(table.)95 3828 y Fe(int)47 b(fits_write_tdim)d(/)j(ffptdm)286 3941 y(\(fitsfile)f(*fptr,)g(int)h (colnum,)e(int)i(naxis,)f(long)h(*naxes,)f(>)h(int)g(*status\))0 4231 y Fd(5.7.3)112 b(Routines)37 b(to)g(Edit)f(Ro)m(ws)h(or)g(Columns) 0 4440 y Fi(1)81 b Fj(Insert)22 b(or)h(delete)g(ro)m(ws)f(in)g(an)h (ASCI)s(I)e(or)i(binary)e(table.)38 b(When)22 b(inserting)f(ro)m(ws)i (all)f(the)h(ro)m(ws)g(follo)m(wing)e(ro)m(w)227 4553 y(FR)m(O)m(W)29 b(are)f(shifted)f(do)m(wn)g(b)m(y)h(NR)m(O)m(WS)g(ro)m (ws;)h(if)e(FR)m(O)m(W)i(=)e(0)h(then)f(the)h(blank)f(ro)m(ws)h(are)g (inserted)e(at)227 4666 y(the)h(b)s(eginning)d(of)j(the)f(table.)40 b(The)26 b(\014rst)g(delete)h(routine)e(deletes)i(NR)m(O)m(WS)g (consecutiv)m(e)h(ro)m(ws)e(starting)227 4779 y(with)i(ro)m(w)i(FIRSTR) m(O)m(W.)g(The)f(second)g(delete)h(routine)e(tak)m(es)j(an)e(input)f (string)g(that)i(lists)e(the)i(ro)m(ws)f(or)227 4891 y(ro)m(w)24 b(ranges)f(\(e.g.,)k('5-10,12,20-30'\),)k(whereas)23 b(the)h(third)d(delete)j(routine)e(tak)m(es)j(an)e(input)f(in)m(teger)h (arra)m(y)227 5004 y(that)35 b(sp)s(eci\014es)e(eac)m(h)i(individual)30 b(ro)m(w)k(to)h(b)s(e)f(deleted.)52 b(In)34 b(b)s(oth)f(latter)i (cases,)h(the)e(input)f(list)g(of)h(ro)m(ws)227 5117 y(to)e(delete)f(m)m(ust)f(b)s(e)g(sorted)h(in)e(ascending)h(order.)41 b(These)31 b(routines)e(up)s(date)h(the)h(NAXIS2)g(k)m(eyw)m(ord)g(to) 227 5230 y(re\015ect)g(the)g(new)f(n)m(um)m(b)s(er)f(of)h(ro)m(ws)h(in) e(the)h(table.)95 5488 y Fe(int)47 b(fits_insert_rows)d(/)j(ffirow)286 5601 y(\(fitsfile)f(*fptr,)g(long)g(firstrow,)g(long)g(nrows,)g(>)i (int)f(*status\))p eop %%Page: 49 57 49 56 bop 0 299 a Fh(5.7.)72 b(ASCI)s(I)29 b(AND)i(BINAR)-8 b(Y)31 b(T)-8 b(ABLE)31 b(R)m(OUTINES)1864 b Fj(49)95 555 y Fe(int)47 b(fits_delete_rows)d(/)j(ffdrow)286 668 y(\(fitsfile)f(*fptr,)g(long)g(firstrow,)g(long)g(nrows,)g(>)i(int)f (*status\))95 894 y(int)g(fits_delete_rowrange)c(/)k(ffdrrg)286 1007 y(\(fitsfile)f(*fptr,)g(char)g(*rangelist,)f(>)j(int)e(*status\)) 95 1233 y(int)h(fits_delete_rowlist)c(/)k(ffdrws)286 1346 y(\(fitsfile)f(*fptr,)g(long)g(*rowlist,)g(long)g(nrows,)g(>)i (int)f(*status\))0 1600 y Fi(2)81 b Fj(Insert)36 b(or)h(delete)h (column\(s\))e(in)g(an)h(ASCI)s(I)f(or)h(binary)e(table.)61 b(When)37 b(inserting,)g(COLNUM)g(sp)s(eci\014es)227 1713 y(the)28 b(column)f(n)m(um)m(b)s(er)g(that)h(the)g(\(\014rst\))g (new)f(column)g(should)f(o)s(ccup)m(y)i(in)f(the)h(table.)40 b(NCOLS)26 b(sp)s(eci\014es)227 1826 y(ho)m(w)35 b(man)m(y)g(columns)e (are)i(to)g(b)s(e)f(inserted.)52 b(An)m(y)35 b(existing)f(columns)f (from)h(this)g(p)s(osition)e(and)i(higher)227 1939 y(are)c(shifted)e(o) m(v)m(er)i(to)g(allo)m(w)e(ro)s(om)h(for)g(the)h(new)e(column\(s\).)40 b(The)29 b(index)e(n)m(um)m(b)s(er)h(on)h(all)f(the)h(follo)m(wing)227 2051 y(k)m(eyw)m(ords)34 b(will)c(b)s(e)j(incremen)m(ted)g(or)g (decremen)m(ted)h(if)e(necessary)i(to)g(re\015ect)g(the)f(new)g(p)s (osition)e(of)j(the)227 2164 y(column\(s\))25 b(in)f(the)i(table:)38 b(TBCOLn,)26 b(TF)m(ORMn,)h(TTYPEn,)e(TUNITn,)h(TNULLn,)g(TSCALn,)f (TZE-)227 2277 y(R)m(On,)43 b(TDISPn,)g(TDIMn,)g(TLMINn,)g(TLMAXn,)g (TDMINn,)g(TDMAXn,)h(TCTYPn,)e(TCRPXn,)227 2390 y(TCR)-10 b(VLn,)29 b(TCDL)-8 b(Tn,)30 b(TCR)m(OTn,)f(and)h(TCUNIn.)95 2644 y Fe(int)47 b(fits_insert_col)d(/)j(fficol)286 2757 y(\(fitsfile)f(*fptr,)g(int)h(colnum,)e(char)i(*ttype,)f(char)h (*tform,)334 2870 y(>)h(int)e(*status\))95 3096 y(int)h (fits_insert_cols)d(/)j(fficls)286 3209 y(\(fitsfile)f(*fptr,)g(int)h (colnum,)e(int)i(ncols,)f(char)h(**ttype,)334 3322 y(char)g(**tform,)e (>)j(int)f(*status\))95 3548 y(int)g(fits_delete_col)d(/)j (ffdcol\(fitsfile)d(*fptr,)i(int)h(colnum,)f(>)h(int)g(*status\))0 3802 y Fi(3)81 b Fj(Cop)m(y)32 b(a)h(column)f(from)g(one)h(HDU)g(to)h (another)e(\(or)h(to)h(the)f(same)g(HDU\).)h(If)e(create)p 3129 3802 28 4 v 34 w(col)h(=)f(TR)m(UE,)h(then)227 3915 y(a)40 b(new)e(column)g(will)e(b)s(e)j(inserted)f(in)f(the)i(output)g (table,)i(at)f(p)s(osition)d(`outcolumn',)k(otherwise)e(the)227 4028 y(existing)e(output)h(column)e(will)g(b)s(e)h(o)m(v)m(erwritten)h (\(in)f(whic)m(h)g(case)i(it)e(m)m(ust)h(ha)m(v)m(e)h(a)f(compatible)f (data)227 4141 y(t)m(yp)s(e\).)k(If)29 b(outcoln)m(um)g(is)f(greater)j (than)e(the)h(n)m(um)m(b)s(er)e(of)h(column)f(in)g(the)i(table,)g(then) f(the)g(new)g(column)227 4254 y(will)g(b)s(e)i(app)s(ended)f(to)j(the)f (end)f(of)g(the)h(table.)45 b(Note)33 b(that)f(the)g(\014rst)f(column)f (in)h(a)h(table)f(is)g(at)i(coln)m(um)227 4366 y(=)j(1.)58 b(The)36 b(standard)f(indexed)f(k)m(eyw)m(ords)j(that)f(related)g(to)h (the)f(column)f(\(e.g.,)k(TDISPn,)e(TUNITn,)227 4479 y(TCRPXn,)30 b(TCDL)-8 b(Tn,)29 b(etc.\))43 b(will)27 b(also)k(b)s(e)e(copied.)95 4734 y Fe(int)47 b(fits_copy_col)e(/)i (ffcpcl)286 4846 y(\(fitsfile)f(*infptr,)f(fitsfile)h(*outfptr,)f(int)i (incolnum,)e(int)i(outcolnum,)334 4959 y(int)g(create_col,)e(>)i(int)g (*status\);)0 5214 y Fi(4)81 b Fj(Mo)s(dify)36 b(the)h(v)m(ector)i (length)e(of)g(a)h(binary)d(table)i(column)f(\(e.g.,)41 b(c)m(hange)e(a)e(column)f(from)h(TF)m(ORMn)g(=)227 5327 y('1E')31 b(to)h('20E'\).)g(The)e(v)m(ector)i(length)d(ma)m(y)i(b)s(e)f (increased)g(or)g(decreased)h(from)f(the)g(curren)m(t)h(v)-5 b(alue.)95 5581 y Fe(int)47 b(fits_modify_vector_len)42 b(/)48 b(ffmvec)286 5694 y(\(fitsfile)e(*fptr,)g(int)h(colnum,)e(long)i (newveclen,)e(>)j(int)e(*status\))p eop %%Page: 50 58 50 57 bop 0 299 a Fj(50)1379 b Fh(CHAPTER)30 b(5.)71 b(BASIC)30 b(CFITSIO)f(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)0 555 y Fd(5.7.4)112 b(Read)38 b(and)h(W)-9 b(rite)35 b(Column)i(Data)g (Routines)0 775 y Fj(The)e(follo)m(wing)e(routines)i(write)f(or)h(read) g(data)h(v)-5 b(alues)35 b(in)f(the)h(curren)m(t)g(ASCI)s(I)f(or)h (binary)f(table)h(extension.)0 888 y(If)e(a)g(write)f(op)s(eration)h (extends)g(b)s(ey)m(ond)f(the)h(curren)m(t)g(size)g(of)g(the)g(table,)h (then)f(the)g(n)m(um)m(b)s(er)f(of)h(ro)m(ws)g(in)f(the)0 1001 y(table)i(will)e(automatically)i(b)s(e)f(increased)h(and)f(the)i (NAXIS2)f(k)m(eyw)m(ord)h(v)-5 b(alue)34 b(will)d(b)s(e)j(up)s(dated.) 51 b(A)m(ttempts)0 1114 y(to)31 b(read)f(b)s(ey)m(ond)g(the)h(end)e(of) i(the)f(table)h(will)c(result)j(in)f(an)h(error.)0 1274 y(Automatic)c(data)f(t)m(yp)s(e)g(con)m(v)m(ersion)g(is)f(p)s(erformed) g(for)g(n)m(umerical)g(data)h(t)m(yp)s(es)g(\(only\))g(if)f(the)h(data) h(t)m(yp)s(e)f(of)g(the)0 1387 y(column)f(\(de\014ned)h(b)m(y)g(the)h (TF)m(ORMn)f(k)m(eyw)m(ord\))h(di\013ers)e(from)h(the)h(data)g(t)m(yp)s (e)f(of)h(the)f(calling)f(routine.)38 b(ASCI)s(I)0 1500 y(and)20 b(binary)e(tables)i(supp)s(ort)f(the)i(follo)m(wing)d(data)j (t)m(yp)s(e)g(v)-5 b(alues:)35 b(TSTRING,)20 b(TBYTE,)g(TSBYTE,)g (TSHOR)-8 b(T,)0 1613 y(TUSHOR)g(T,)22 b(TINT,)g(TUINT,)f(TLONG,)i (TLONGLONG,)f(TULONG,)g(TFLO)m(A)-8 b(T,)23 b(or)f(TDOUBLE.)h(Binary)0 1726 y(tables)37 b(also)g(supp)s(ort)e(TLOGICAL)h(\(in)m(ternally)g (mapp)s(ed)g(to)h(the)h(`c)m(har')g(data)g(t)m(yp)s(e\),)h(TCOMPLEX,)e (and)0 1839 y(TDBLCOMPLEX.)0 1999 y(Note)25 b(that)g(within)c(the)j (con)m(text)i(of)e(these)g(routines,)h(the)f(TSTRING)f(data)h(t)m(yp)s (e)g(corresp)s(onds)f(to)h(a)h(C)e('c)m(har**')0 2112 y(data)35 b(t)m(yp)s(e,)h(i.e.,)g(a)f(p)s(oin)m(ter)e(to)j(an)e(arra)m (y)h(of)g(p)s(oin)m(ters)e(to)i(an)g(arra)m(y)g(of)g(c)m(haracters.)54 b(This)33 b(is)g(di\013eren)m(t)h(from)0 2225 y(the)e(k)m(eyw)m(ord)h (reading)e(and)g(writing)f(routines)h(where)h(TSTRING)f(corresp)s(onds) g(to)h(a)h(C)e('c)m(har*')j(data)f(t)m(yp)s(e,)0 2338 y(i.e.,)f(a)f(single)f(p)s(oin)m(ter)g(to)i(an)f(arra)m(y)g(of)g(c)m (haracters.)45 b(When)30 b(reading)h(strings)e(from)i(a)g(table,)h(the) f(c)m(har)h(arra)m(ys)0 2451 y(ob)m(viously)d(m)m(ust)h(ha)m(v)m(e)i(b) s(een)e(allo)s(cated)g(long)g(enough)g(to)h(hold)e(the)i(whole)e(FITS)h (table)g(string.)0 2611 y(Numerical)h(data)i(v)-5 b(alues)32 b(are)h(automatically)g(scaled)f(b)m(y)g(the)h(TSCALn)e(and)h(TZER)m (On)f(k)m(eyw)m(ord)i(v)-5 b(alues)32 b(\(if)0 2724 y(they)f(exist\).)0 2884 y(In)25 b(the)g(case)i(of)e(binary)f(tables)h(with)f(v)m(ector)j (elemen)m(ts,)g(the)f('felem')f(parameter)h(de\014nes)f(the)g(starting) g(elemen)m(t)0 2997 y(\(b)s(eginning)g(with)h(1,)i(not)g(0\))g(within)d (the)i(cell)g(\(a)h(cell)e(is)g(de\014ned)g(as)i(the)f(in)m(tersection) g(of)h(a)f(ro)m(w)h(and)e(a)i(column)0 3110 y(and)e(ma)m(y)h(con)m (tain)g(a)h(single)d(v)-5 b(alue)26 b(or)h(a)g(v)m(ector)h(of)f(v)-5 b(alues\).)39 b(The)26 b(felem)h(parameter)g(is)f(ignored)f(when)h (dealing)0 3223 y(with)33 b(ASCI)s(I)f(tables.)51 b(Similarly)-8 b(,)32 b(in)g(the)j(case)f(of)h(binary)d(tables)h(the)i('nelemen)m(ts') f(parameter)g(sp)s(eci\014es)f(the)0 3336 y(total)27 b(n)m(um)m(b)s(er)e(of)h(v)m(ector)i(v)-5 b(alues)26 b(to)h(b)s(e)e(read)h(or)h(written)e(\(con)m(tin)m(uing)h(on)g (subsequen)m(t)f(ro)m(ws)i(if)e(required\))g(and)0 3448 y(not)31 b(the)f(n)m(um)m(b)s(er)f(of)i(table)f(cells.)0 3714 y Fi(1)81 b Fj(W)-8 b(rite)30 b(elemen)m(ts)h(in)m(to)f(an)h(ASCI) s(I)e(or)h(binary)e(table)j(column.)0 3980 y(The)38 b(\014rst)f (routine)g(simply)f(writes)h(the)h(arra)m(y)h(of)f(v)-5 b(alues)38 b(to)h(the)f(FITS)g(\014le)f(\(doing)g(data)i(t)m(yp)s(e)g (con)m(v)m(ersion)0 4093 y(if)g(necessary\))i(whereas)f(the)h(second)f (routine)g(will)d(substitute)j(the)g(appropriate)f(FITS)h(n)m(ull)e(v) -5 b(alue)40 b(for)g(all)0 4206 y(elemen)m(ts)33 b(whic)m(h)f(are)h (equal)g(to)g(the)g(input)e(v)-5 b(alue)33 b(of)g(n)m(ulv)-5 b(al)31 b(\(note)j(that)f(this)f(parameter)h(giv)m(es)h(the)f(address)0 4319 y(of)40 b(n)m(ulv)-5 b(al,)42 b(not)e(the)g(n)m(ull)e(v)-5 b(alue)40 b(itself)7 b(\).)70 b(F)-8 b(or)40 b(in)m(teger)h(columns)e (the)h(FITS)g(n)m(ull)e(v)-5 b(alue)39 b(is)h(de\014ned)f(b)m(y)h(the)0 4432 y(TNULLn)32 b(k)m(eyw)m(ord)i(\(an)g(error)e(is)h(returned)f(if)g (the)i(k)m(eyw)m(ord)f(do)s(esn't)g(exist\).)50 b(F)-8 b(or)34 b(\015oating)f(p)s(oin)m(t)f(columns)0 4545 y(the)i(sp)s(ecial) f(IEEE)h(NaN)h(\(Not-a-Num)m(b)s(er\))h(v)-5 b(alue)34 b(will)d(b)s(e)j(written)f(in)m(to)i(the)f(FITS)g(\014le.)51 b(If)34 b(a)h(n)m(ull)d(p)s(oin)m(ter)0 4658 y(is)g(en)m(tered)h(for)g (n)m(ulv)-5 b(al,)32 b(then)h(the)g(n)m(ull)e(v)-5 b(alue)32 b(is)g(ignored)g(and)h(this)f(routine)f(b)s(eha)m(v)m(es)j(the)f(same)g (as)h(the)f(\014rst)0 4771 y(routine.)39 b(The)26 b(second)i(routine)e (m)m(ust)h(not)h(b)s(e)e(used)h(to)h(write)e(to)i(v)-5 b(ariable)26 b(length)h(arra)m(y)h(columns.)38 b(The)27 b(third)0 4883 y(routine)i(simply)f(writes)i(unde\014ned)e(pixel)h(v)-5 b(alues)29 b(to)i(the)g(column.)95 5149 y Fe(int)47 b(fits_write_col)d (/)k(ffpcl)286 5262 y(\(fitsfile)e(*fptr,)g(int)h(datatype,)e(int)i (colnum,)f(long)g(firstrow,)334 5375 y(long)h(firstelem,)e(long)h (nelements,)f(DTYPE)i(*array,)f(>)h(int)g(*status\))95 5601 y(int)g(fits_write_colnull)c(/)48 b(ffpcn)286 5714 y(\(fitsfile)e(*fptr,)g(int)h(datatype,)e(int)i(colnum,)f(long)g (firstrow,)p eop %%Page: 51 59 51 58 bop 0 299 a Fh(5.7.)72 b(ASCI)s(I)29 b(AND)i(BINAR)-8 b(Y)31 b(T)-8 b(ABLE)31 b(R)m(OUTINES)1864 b Fj(51)286 555 y Fe(long)47 b(firstelem,)e(long)i(nelements,)e(DTYPE)h(*array,)g (DTYPE)g(*nulval,)286 668 y(>)i(int)f(*status\))143 894 y(int)g(fits_write_col_null)c(/)k(ffpclu)334 1007 y(\(fitsfile)e (*fptr,)h(int)h(colnum,)f(long)h(firstrow,)e(long)i(firstelem,)382 1120 y(long)f(nelements,)f(>)j(int)f(*status\))0 1375 y Fi(2)81 b Fj(Read)33 b(elemen)m(ts)h(from)f(an)g(ASCI)s(I)f(or)i (binary)d(table)i(column.)49 b(The)33 b(data)h(t)m(yp)s(e)g(parameter)g (sp)s(eci\014es)e(the)227 1488 y(data)c(t)m(yp)s(e)g(of)g(the)f(`n)m (ulv)-5 b(al')27 b(and)g(`arra)m(y')h(p)s(oin)m(ters;)g(Unde\014ned)d (arra)m(y)j(elemen)m(ts)g(will)d(b)s(e)i(returned)f(with)227 1601 y(a)k(v)-5 b(alue)29 b(=)f(*n)m(ullv)-5 b(al,)28 b(\(note)i(that)g(this)e(parameter)i(giv)m(es)f(the)h(address)e(of)h (the)h(n)m(ull)d(v)-5 b(alue,)29 b(not)h(the)f(n)m(ull)227 1714 y(v)-5 b(alue)30 b(itself)7 b(\))30 b(unless)f(n)m(ulv)-5 b(al)30 b(=)g(0)h(or)g(*n)m(ulv)-5 b(al)29 b(=)i(0,)g(in)e(whic)m(h)h (case)i(no)e(c)m(hec)m(king)i(for)e(unde\014ned)f(pixels)227 1827 y(will)i(b)s(e)i(p)s(erformed.)48 b(The)33 b(second)g(routine)g (is)f(similar)f(except)j(that)g(an)m(y)g(unde\014ned)d(pixels)h(will)f (ha)m(v)m(e)227 1940 y(the)g(corresp)s(onding)d(n)m(ullarra)m(y)h (elemen)m(t)i(set)g(equal)f(to)h(TR)m(UE)f(\(=)h(1\).)227 2089 y(An)m(y)c(column,)f(regardless)f(of)h(it's)g(in)m(trinsic)e(data) j(t)m(yp)s(e,)g(ma)m(y)g(b)s(e)e(read)i(as)f(a)g(string.)39 b(It)26 b(should)e(b)s(e)i(noted)227 2202 y(ho)m(w)m(ev)m(er)32 b(that)f(reading)e(a)i(n)m(umeric)e(column)g(as)i(a)g(string)e(is)g(10) j(-)e(100)i(times)e(slo)m(w)m(er)g(than)g(reading)g(the)227 2315 y(same)22 b(column)f(as)g(a)h(n)m(um)m(b)s(er)e(due)h(to)i(the)e (large)h(o)m(v)m(erhead)h(in)d(constructing)h(the)h(formatted)g (strings.)36 b(The)227 2428 y(displa)m(y)24 b(format)i(of)f(the)h (returned)e(strings)g(will)f(b)s(e)i(determined)f(b)m(y)h(the)h(TDISPn) e(k)m(eyw)m(ord,)j(if)d(it)h(exists,)227 2541 y(otherwise)31 b(b)m(y)g(the)g(data)h(t)m(yp)s(e)f(of)g(the)g(column.)42 b(The)30 b(length)h(of)g(the)g(returned)f(strings)g(\(not)h(including) 227 2654 y(the)26 b(n)m(ull)d(terminating)i(c)m(haracter\))i(can)f(b)s (e)f(determined)f(with)g(the)i(\014ts)p 2703 2654 28 4 v 32 w(get)p 2855 2654 V 34 w(col)p 3000 2654 V 33 w(displa)m(y)p 3313 2654 V 31 w(width)e(routine.)227 2767 y(The)30 b(follo)m(wing)f(TDISPn)g(displa)m(y)g(formats)h(are)h (curren)m(tly)e(supp)s(orted:)418 3011 y Fe(Iw.m)142 b(Integer)418 3124 y(Ow.m)g(Octal)47 b(integer)418 3237 y(Zw.m)142 b(Hexadecimal)45 b(integer)418 3350 y(Fw.d)142 b(Fixed)47 b(floating)e(point)418 3463 y(Ew.d)142 b(Exponential)45 b(floating)h(point)418 3576 y(Dw.d)142 b(Exponential)45 b(floating)h(point)418 3689 y(Gw.d)142 b(General;)46 b(uses)g(Fw.d)h(if)g(significance)e(not)i(lost,)f(else)h(Ew.d)227 3934 y Fj(where)24 b(w)h(is)e(the)i(width)e(in)g(c)m(haracters)j(of)f (the)g(displa)m(y)m(ed)e(v)-5 b(alues,)26 b(m)e(is)g(the)g(minim)m(um)e (n)m(um)m(b)s(er)i(of)g(digits)227 4046 y(displa)m(y)m(ed,)j(and)g(d)g (is)g(the)g(n)m(um)m(b)s(er)g(of)g(digits)g(to)h(the)g(righ)m(t)f(of)g (the)h(decimal.)39 b(The)27 b(.m)g(\014eld)f(is)h(optional.)95 4302 y Fe(int)47 b(fits_read_col)e(/)i(ffgcv)286 4415 y(\(fitsfile)f(*fptr,)g(int)h(datatype,)e(int)i(colnum,)f(long)g (firstrow,)g(long)g(firstelem,)334 4528 y(long)h(nelements,)e(DTYPE)h (*nulval,)g(DTYPE)g(*array,)g(int)h(*anynul,)e(int)i(*status\))95 4753 y(int)g(fits_read_colnull)c(/)48 b(ffgcf)286 4866 y(\(fitsfile)e(*fptr,)g(int)h(datatype,)e(int)i(colnum,)f(long)g (firstrow,)g(long)g(firstelem,)286 4979 y(long)h(nelements,)e(DTYPE)h (*array,)g(char)h(*nullarray,)e(int)h(*anynul,)g(int)h(*status\))0 5269 y Fd(5.7.5)112 b(Ro)m(w)37 b(Selection)f(and)j(Calculator)d (Routines)0 5488 y Fj(These)21 b(routines)e(all)h(parse)h(and)f(ev)-5 b(aluate)22 b(an)e(input)f(string)h(con)m(taining)h(a)g(user)f (de\014ned)g(arithmetic)g(expression.)0 5601 y(The)29 b(\014rst)f(3)i(routines)e(select)i(ro)m(ws)f(in)f(a)i(FITS)e(table,)i (based)f(on)g(whether)g(the)g(expression)f(ev)-5 b(aluates)30 b(to)g(true)0 5714 y(\(not)e(equal)e(to)i(zero\))g(or)f(false)g (\(zero\).)41 b(The)27 b(other)g(routines)f(ev)-5 b(aluate)28 b(the)f(expression)f(and)g(calculate)i(a)f(v)-5 b(alue)p eop %%Page: 52 60 52 59 bop 0 299 a Fj(52)1379 b Fh(CHAPTER)30 b(5.)71 b(BASIC)30 b(CFITSIO)f(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)0 555 y Fj(for)c(eac)m(h)i(ro)m(w)f(of)g(the)g(table.)39 b(The)26 b(allo)m(w)m(ed)h(expression)e(syn)m(tax)j(is)d(describ)s(ed)g (in)g(the)i(ro)m(w)g(\014lter)f(section)g(in)g(the)0 668 y(`Extended)32 b(File)f(Name)i(Syn)m(tax')g(c)m(hapter)g(of)f(this) f(do)s(cumen)m(t.)46 b(The)32 b(expression)f(ma)m(y)i(also)f(b)s(e)f (written)h(to)h(a)0 781 y(text)h(\014le,)g(and)f(the)h(name)f(of)h(the) f(\014le,)h(prep)s(ended)d(with)h(a)i('@')g(c)m(haracter)h(ma)m(y)f(b)s (e)f(supplied)d(for)j(the)h('expr')0 894 y(parameter)d(\(e.g.)42 b('@\014lename.txt'\).)f(The)30 b(expression)f(in)g(the)h(\014le)g(can) g(b)s(e)g(arbitrarily)d(complex)j(and)g(extend)0 1007 y(o)m(v)m(er)35 b(m)m(ultiple)d(lines)h(of)h(the)g(\014le.)52 b(Lines)32 b(that)j(b)s(egin)e(with)g(2)h(slash)f(c)m(haracters)j (\('//'\))g(will)c(b)s(e)h(ignored)h(and)0 1120 y(ma)m(y)d(b)s(e)f (used)f(to)i(add)f(commen)m(ts)h(to)h(the)e(\014le.)0 1342 y Fi(1)81 b Fj(Ev)-5 b(aluate)37 b(a)g(b)s(o)s(olean)f(expression) g(o)m(v)m(er)i(the)g(indicated)d(ro)m(ws,)k(returning)c(an)i(arra)m(y)h (of)f(\015ags)g(indicating)227 1455 y(whic)m(h)29 b(ro)m(ws)i(ev)-5 b(aluated)30 b(to)h(TR)m(UE/F)-10 b(ALSE)95 1676 y Fe(int)47 b(fits_find_rows)d(/)k(fffrow)286 1789 y(\(fitsfile)e(*fptr,)93 b(char)47 b(*expr,)f(long)h(firstrow,)e(long)i(nrows,)286 1902 y(>)h(long)e(*n_good_rows,)f(char)h(*row_status,)92 b(int)47 b(*status\))0 2124 y Fi(2)81 b Fj(Find)28 b(the)j(\014rst)f (ro)m(w)g(whic)m(h)f(satis\014es)h(the)h(input)d(b)s(o)s(olean)h (expression)95 2346 y Fe(int)47 b(fits_find_first_row)c(/)k(ffffrw)286 2459 y(\(fitsfile)f(*fptr,)93 b(char)47 b(*expr,)f(>)i(long)e(*rownum,) g(int)h(*status\))0 2681 y Fi(3)81 b Fj(Ev)-5 b(aluate)34 b(an)g(expression)g(on)g(all)f(ro)m(ws)i(of)f(a)h(table.)53 b(If)34 b(the)g(input)f(and)h(output)g(\014les)f(are)i(not)g(the)f (same,)227 2794 y(cop)m(y)39 b(the)f(TR)m(UE)g(ro)m(ws)h(to)f(the)h (output)e(\014le.)63 b(If)38 b(the)g(\014les)f(are)i(the)f(same,)j (delete)d(the)g(F)-10 b(ALSE)38 b(ro)m(ws)227 2907 y(\(preserv)m(e)31 b(the)g(TR)m(UE)f(ro)m(ws\).)95 3129 y Fe(int)47 b(fits_select_rows)d (/)j(ffsrow)286 3242 y(\(fitsfile)f(*infptr,)f(fitsfile)h(*outfptr,)93 b(char)46 b(*expr,)94 b(>)48 b(int)f(*status)e(\))0 3463 y Fi(4)81 b Fj(Calculate)26 b(an)h(expression)e(for)i(the)f(indicated)g (ro)m(ws)g(of)h(a)g(table,)h(returning)d(the)i(results,)f(cast)i(as)f (datat)m(yp)s(e)227 3576 y(\(TSHOR)-8 b(T,)32 b(TDOUBLE,)h(etc\),)h(in) d(arra)m(y)-8 b(.)48 b(If)31 b(n)m(ulv)-5 b(al==NULL,)31 b(UNDEFs)i(will)c(b)s(e)j(zero)s(ed)g(out.)47 b(F)-8 b(or)227 3689 y(v)m(ector)37 b(results,)e(the)g(n)m(um)m(b)s(er)e(of)i (elemen)m(ts)h(returned)d(ma)m(y)j(b)s(e)e(less)g(than)h(nelemen)m(ts)f (if)g(nelemen)m(ts)h(is)227 3802 y(not)d(an)g(ev)m(en)h(m)m(ultiple)c (of)j(the)g(result)f(dimension.)42 b(Call)31 b(\014ts)p 2392 3802 28 4 v 32 w(test)p 2570 3802 V 34 w(expr)g(to)h(obtain)g(the) g(dimensions)d(of)227 3915 y(the)i(results.)95 4137 y Fe(int)47 b(fits_calc_rows)d(/)k(ffcrow)286 4250 y(\(fitsfile)e(*fptr,) 93 b(int)47 b(datatype,)f(char)g(*expr,)g(long)h(firstrow,)334 4363 y(long)g(nelements,)e(void)h(*nulval,)g(>)h(void)g(*array,)94 b(int)46 b(*anynul,)g(int)h(*status\))0 4585 y Fi(5)81 b Fj(Ev)-5 b(aluate)32 b(an)h(expression)e(and)i(write)e(the)i(result)f (either)g(to)i(a)f(column)e(\(if)h(the)h(expression)e(is)h(a)h (function)227 4698 y(of)d(other)g(columns)f(in)f(the)i(table\))g(or)g (to)g(a)h(k)m(eyw)m(ord)f(\(if)f(the)h(expression)e(ev)-5 b(aluates)31 b(to)f(a)g(constan)m(t)i(and)227 4811 y(is)e(not)g(a)h (function)e(of)i(other)f(columns)g(in)f(the)h(table\).)41 b(In)30 b(the)h(former)e(case,)j(the)f(parName)f(parameter)227 4924 y(is)39 b(the)h(name)f(of)h(the)g(column)e(\(whic)m(h)h(ma)m(y)h (or)f(ma)m(y)h(not)g(already)f(exist\))h(in)m(to)f(whic)m(h)g(to)h (write)f(the)227 5036 y(results,)e(and)g(parInfo)e(con)m(tains)i(an)g (optional)e(TF)m(ORM)i(k)m(eyw)m(ord)g(v)-5 b(alue)37 b(if)e(a)i(new)f(column)g(is)f(b)s(eing)227 5149 y(created.)42 b(If)28 b(a)h(TF)m(ORM)h(v)-5 b(alue)28 b(is)g(not)h(sp)s(eci\014ed)f (then)g(a)i(default)e(format)h(will)e(b)s(e)h(used,)h(dep)s(ending)d (on)227 5262 y(the)35 b(expression.)53 b(If)34 b(the)h(expression)e(ev) -5 b(aluates)36 b(to)f(a)g(constan)m(t,)i(then)e(the)g(result)e(will)f (b)s(e)i(written)g(to)227 5375 y(the)28 b(k)m(eyw)m(ord)g(name)f(giv)m (en)g(b)m(y)h(the)f(parName)h(parameter,)h(and)d(the)i(parInfo)e (parameter)i(ma)m(y)g(b)s(e)f(used)227 5488 y(to)k(supply)d(an)i (optional)g(commen)m(t)h(for)f(the)g(k)m(eyw)m(ord.)42 b(If)29 b(the)i(k)m(eyw)m(ord)g(do)s(es)f(not)g(already)g(exist,)g (then)227 5601 y(the)g(name)f(of)h(the)g(k)m(eyw)m(ord)g(m)m(ust)f(b)s (e)g(preceded)g(with)f(a)i('#')f(c)m(haracter,)j(otherwise)d(the)g (result)g(will)e(b)s(e)227 5714 y(written)j(to)h(a)g(column)e(with)g (that)i(name.)p eop %%Page: 53 61 53 60 bop 0 299 a Fh(5.8.)72 b(UTILITY)30 b(R)m(OUTINES)2693 b Fj(53)95 555 y Fe(int)47 b(fits_calculator)d(/)j(ffcalc)286 668 y(\(fitsfile)f(*infptr,)f(char)i(*expr,)f(fitsfile)f(*outfptr,)h (char)g(*parName,)334 781 y(char)h(*parInfo,)e(>)95 b(int)47 b(*status\))0 1032 y Fi(6)81 b Fj(This)37 b(calculator)j(routine)f(is)f (similar)f(to)j(the)g(previous)e(routine,)j(except)g(that)f(the)g (expression)e(is)h(only)227 1145 y(ev)-5 b(aluated)41 b(o)m(v)m(er)g(the)f(sp)s(eci\014ed)f(ro)m(w)h(ranges.)70 b(nranges)39 b(sp)s(eci\014es)g(the)h(n)m(um)m(b)s(er)f(of)h(ro)m(w)h (ranges,)i(and)227 1258 y(\014rstro)m(w)30 b(and)g(lastro)m(w)g(giv)m (e)h(the)g(starting)f(and)g(ending)f(ro)m(w)h(n)m(um)m(b)s(er)f(of)i (eac)m(h)g(range.)95 1509 y Fe(int)47 b(fits_calculator_rng)c(/)k (ffcalc_rng)286 1622 y(\(fitsfile)f(*infptr,)f(char)i(*expr,)f (fitsfile)f(*outfptr,)h(char)g(*parName,)334 1735 y(char)h(*parInfo,)e (int)i(nranges,)e(long)i(*firstrow,)e(long)i(*lastrow)334 1848 y(>)95 b(int)47 b(*status\))0 2099 y Fi(7)81 b Fj(Ev)-5 b(aluate)30 b(the)h(giv)m(en)f(expression)f(and)h(return)f(information) g(on)h(the)h(result.)95 2350 y Fe(int)47 b(fits_test_expr)d(/)k(fftexp) 286 2463 y(\(fitsfile)e(*fptr,)g(char)g(*expr,)g(>)i(int)f(*datatype,)e (long)h(*nelem,)g(int)h(*naxis,)334 2575 y(long)g(*naxes,)f(int)g (*status\))0 2908 y Ff(5.8)135 b(Utilit)l(y)47 b(Routines)0 3161 y Fd(5.8.1)112 b(File)37 b(Chec)m(ksum)g(Routines)0 3380 y Fj(The)c(follo)m(wing)e(routines)h(either)h(compute)g(or)h(v)-5 b(alidate)32 b(the)i(c)m(hec)m(ksums)f(for)g(the)h(CHDU.)g(The)e(D)m(A) -8 b(T)g(ASUM)0 3493 y(k)m(eyw)m(ord)33 b(is)e(used)g(to)i(store)f(the) h(n)m(umerical)d(v)-5 b(alue)32 b(of)g(the)g(32-bit,)h(1's)g(complemen) m(t)f(c)m(hec)m(ksum)h(for)f(the)g(data)0 3606 y(unit)25 b(alone.)39 b(If)25 b(there)h(is)g(no)f(data)i(unit)e(then)g(the)h(v)-5 b(alue)26 b(is)f(set)h(to)h(zero.)40 b(The)26 b(n)m(umerical)e(v)-5 b(alue)26 b(is)f(stored)h(as)g(an)0 3719 y(ASCI)s(I)20 b(string)h(of)i(digits,)f(enclosed)g(in)e(quotes,)25 b(b)s(ecause)d(the)g(v)-5 b(alue)22 b(ma)m(y)g(b)s(e)f(to)s(o)i(large)f (to)h(represen)m(t)f(as)g(a)h(32-bit)0 3832 y(signed)k(in)m(teger.)40 b(The)27 b(CHECKSUM)g(k)m(eyw)m(ord)i(is)e(used)g(to)h(store)h(the)f (ASCI)s(I)e(enco)s(ded)i(COMPLEMENT)f(of)0 3945 y(the)f(c)m(hec)m(ksum) h(for)f(the)h(en)m(tire)f(HDU.)h(Storing)e(the)i(complemen)m(t,)g (rather)f(than)g(the)h(actual)f(c)m(hec)m(ksum,)i(forces)0 4058 y(the)k(c)m(hec)m(ksum)h(for)f(the)h(whole)e(HDU)i(to)g(equal)f (zero.)47 b(If)31 b(the)i(\014le)e(has)h(b)s(een)f(mo)s(di\014ed)f (since)i(the)g(c)m(hec)m(ksums)0 4170 y(w)m(ere)39 b(computed,)i(then)e (the)g(HDU)g(c)m(hec)m(ksum)h(will)c(usually)g(not)j(equal)g(zero.)66 b(These)39 b(c)m(hec)m(ksum)g(k)m(eyw)m(ord)0 4283 y(con)m(v)m(en)m (tions)33 b(are)g(based)f(on)g(a)g(pap)s(er)f(b)m(y)h(Rob)g(Seaman)g (published)d(in)i(the)h(pro)s(ceedings)f(of)h(the)h(AD)m(ASS)f(IV)0 4396 y(conference)h(in)d(Baltimore)i(in)e(No)m(v)m(em)m(b)s(er)j(1994)h (and)d(a)h(later)g(revision)e(in)g(June)h(1995.)47 b(See)32 b(App)s(endix)d(B)j(for)0 4509 y(the)f(de\014nition)d(of)i(the)h (parameters)f(used)g(in)f(these)i(routines.)0 4760 y Fi(1)81 b Fj(Compute)33 b(and)g(write)g(the)h(D)m(A)-8 b(T)g(ASUM)35 b(and)e(CHECKSUM)g(k)m(eyw)m(ord)h(v)-5 b(alues)33 b(for)g(the)h(CHDU)g(in)m(to)g(the)227 4873 y(curren)m(t)e(header.)46 b(If)32 b(the)g(k)m(eyw)m(ords)h(already)f (exist,)g(their)g(v)-5 b(alues)31 b(will)f(b)s(e)h(up)s(dated)g(only)g (if)h(necessary)227 4986 y(\(i.e.,)f(if)f(the)g(\014le)g(has)g(b)s(een) f(mo)s(di\014ed)g(since)g(the)i(original)e(k)m(eyw)m(ord)h(v)-5 b(alues)30 b(w)m(ere)h(computed\).)95 5237 y Fe(int)47 b(fits_write_chksum)c(/)48 b(ffpcks)286 5350 y(\(fitsfile)e(*fptr,)g(>) h(int)g(*status\))0 5601 y Fi(2)81 b Fj(Up)s(date)28 b(the)h(CHECKSUM)e(k)m(eyw)m(ord)i(v)-5 b(alue)28 b(in)f(the)i(CHDU,)g (assuming)e(that)i(the)f(D)m(A)-8 b(T)g(ASUM)30 b(k)m(eyw)m(ord)227 5714 y(exists)35 b(and)g(already)g(has)g(the)h(correct)g(v)-5 b(alue.)55 b(This)34 b(routine)g(calculates)i(the)g(new)f(c)m(hec)m (ksum)h(for)f(the)p eop %%Page: 54 62 54 61 bop 0 299 a Fj(54)1379 b Fh(CHAPTER)30 b(5.)71 b(BASIC)30 b(CFITSIO)f(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)227 555 y Fj(curren)m(t)40 b(header)g(unit,)i(adds)d(it)h(to)h(the)f(data)h (unit)e(c)m(hec)m(ksum,)44 b(enco)s(des)c(the)g(v)-5 b(alue)40 b(in)m(to)g(an)g(ASCI)s(I)227 668 y(string,)30 b(and)g(writes)f(the)i(string)e(to)i(the)g(CHECKSUM)e(k)m(eyw)m(ord.)95 897 y Fe(int)47 b(fits_update_chksum)c(/)48 b(ffupck)286 1010 y(\(fitsfile)e(*fptr,)g(>)h(int)g(*status\))0 1238 y Fi(3)81 b Fj(V)-8 b(erify)34 b(the)g(CHDU)h(b)m(y)g(computing)e(the)i (c)m(hec)m(ksums)g(and)f(comparing)g(them)g(with)f(the)i(k)m(eyw)m (ords.)53 b(The)227 1351 y(data)34 b(unit)e(is)g(v)m(eri\014ed)g (correctly)h(if)f(the)i(computed)f(c)m(hec)m(ksum)g(equals)g(the)g(v)-5 b(alue)33 b(of)g(the)g(D)m(A)-8 b(T)g(ASUM)227 1464 y(k)m(eyw)m(ord.)64 b(The)37 b(c)m(hec)m(ksum)i(for)f(the)g(en)m(tire)f(HDU)i(\(header)f (plus)e(data)j(unit\))d(is)h(correct)i(if)e(it)h(equals)227 1577 y(zero.)47 b(The)32 b(output)f(D)m(A)-8 b(T)g(A)m(OK)34 b(and)d(HDUOK)i(parameters)f(in)f(this)g(routine)g(are)h(in)m(tegers)h (whic)m(h)e(will)227 1690 y(ha)m(v)m(e)36 b(a)f(v)-5 b(alue)34 b(=)g(1)h(if)e(the)i(data)g(or)f(HDU)h(is)f(v)m(eri\014ed)f (correctly)-8 b(,)37 b(a)e(v)-5 b(alue)34 b(=)g(0)h(if)e(the)i(D)m(A)-8 b(T)g(ASUM)36 b(or)227 1803 y(CHECKSUM)29 b(k)m(eyw)m(ord)g(is)g(not)g (presen)m(t,)h(or)f(v)-5 b(alue)29 b(=)g(-1)h(if)e(the)i(computed)f(c)m (hec)m(ksum)h(is)e(not)i(correct.)95 2144 y Fe(int)47 b(fits_verify_chksum)c(/)48 b(ffvcks)286 2257 y(\(fitsfile)e(*fptr,)g (>)h(int)g(*dataok,)f(int)h(*hduok,)e(int)i(*status\))0 2486 y Fi(4)81 b Fj(Compute)40 b(and)g(return)g(the)h(c)m(hec)m(ksum)g (v)-5 b(alues)40 b(for)h(the)g(CHDU)g(without)f(creating)h(or)g(mo)s (difying)d(the)227 2599 y(CHECKSUM)33 b(and)h(D)m(A)-8 b(T)g(ASUM)35 b(k)m(eyw)m(ords.)52 b(This)32 b(routine)h(is)g(used)g (in)m(ternally)f(b)m(y)i(\013v)m(c)m(ks,)i(but)d(ma)m(y)227 2711 y(b)s(e)d(useful)f(in)g(other)h(situations)f(as)i(w)m(ell.)95 2940 y Fe(int)47 b(fits_get_chksum/)d(/ffgcks)286 3053 y(\(fitsfile)i(*fptr,)g(>)h(unsigned)f(long)g(*datasum,)g(unsigned)f (long)i(*hdusum,)334 3166 y(int)g(*status\))0 3394 y Fi(5)81 b Fj(Enco)s(de)23 b(a)h(c)m(hec)m(ksum)g(v)-5 b(alue)23 b(in)m(to)g(a)h(16-c)m(haracter)j(string.)37 b(If)23 b(complm)g(is)f(non-zero)j(\(true\))f(then)f(the)h(32-bit)227 3507 y(sum)30 b(v)-5 b(alue)30 b(will)d(b)s(e)j(complemen)m(ted)g(b)s (efore)g(enco)s(ding.)95 3736 y Fe(int)47 b(fits_encode_chksum)c(/)48 b(ffesum)286 3849 y(\(unsigned)e(long)g(sum,)h(int)g(complm,)f(>)h (char)g(*ascii\);)0 4077 y Fi(6)81 b Fj(Deco)s(de)24 b(a)f(16-c)m(haracter)j(c)m(hec)m(ksum)e(string)e(in)m(to)g(a)i (unsigned)d(long)h(v)-5 b(alue.)38 b(If)23 b(is)f(non-zero)h(\(true\).) 39 b(then)23 b(the)227 4190 y(32-bit)32 b(sum)e(v)-5 b(alue)31 b(will)e(b)s(e)i(complemen)m(ted)g(after)h(deco)s(ding.)43 b(The)31 b(c)m(hec)m(ksum)h(v)-5 b(alue)31 b(is)g(also)g(returned)227 4303 y(as)g(the)f(v)-5 b(alue)30 b(of)h(the)f(function.)95 4532 y Fe(unsigned)46 b(long)h(fits_decode_chksum)42 b(/)48 b(ffdsum)525 4645 y(\(char)e(*ascii,)g(int)h(complm,)f(>)h (unsigned)f(long)h(*sum\);)0 4930 y Fd(5.8.2)112 b(Date)38 b(and)g(Time)e(Utilit)m(y)e(Routines)0 5149 y Fj(The)29 b(follo)m(wing)f(routines)h(help)f(to)j(construct)f(or)f(parse)h(the)g (FITS)f(date/time)h(strings.)40 b(Starting)29 b(in)f(the)i(y)m(ear)0 5262 y(2000,)k(the)d(FITS)g(D)m(A)-8 b(TE)32 b(k)m(eyw)m(ord)g(v)-5 b(alues)30 b(\(and)i(the)f(v)-5 b(alues)31 b(of)g(other)h(`D)m(A)-8 b(TE-')33 b(k)m(eyw)m(ords\))f(m)m(ust)f(ha)m(v)m(e)i(the)0 5375 y(form)j('YYYY-MM-DD')k(\(date)e(only\))e(or)h ('YYYY-MM-DDThh:mm:ss.ddd...')61 b(\(date)38 b(and)e(time\))g(where)0 5488 y(the)30 b(n)m(um)m(b)s(er)f(of)i(decimal)e(places)h(in)f(the)h (seconds)g(v)-5 b(alue)30 b(is)f(optional.)40 b(These)30 b(times)g(are)g(in)f(UTC.)h(The)g(older)0 5601 y('dd/mm/yy')d(date)g (format)g(ma)m(y)h(not)f(b)s(e)f(used)g(for)h(dates)h(after)f(01)h(Jan) m(uary)e(2000.)42 b(See)27 b(App)s(endix)d(B)j(for)g(the)0 5714 y(de\014nition)h(of)j(the)f(parameters)h(used)e(in)g(these)i (routines.)p eop %%Page: 55 63 55 62 bop 0 299 a Fh(5.8.)72 b(UTILITY)30 b(R)m(OUTINES)2693 b Fj(55)0 555 y Fi(1)81 b Fj(Get)23 b(the)f(curren)m(t)f(system)i (date.)38 b(C)22 b(already)f(pro)m(vides)g(standard)g(library)f (routines)h(for)g(getting)i(the)f(curren)m(t)227 668 y(date)k(and)e(time,)i(but)e(this)g(routine)g(is)g(pro)m(vided)g(for)g (compatibilit)m(y)g(with)f(the)i(F)-8 b(ortran)26 b(FITSIO)e(library)-8 b(.)227 781 y(The)30 b(returned)f(y)m(ear)j(has)e(4)g(digits)f(\(1999,) k(2000,)g(etc.\))95 1026 y Fe(int)47 b(fits_get_system_date/ffgsd)o(t) 286 1139 y(\()h(>)f(int)g(*day,)g(int)f(*month,)g(int)h(*year,)f(int)h (*status)f(\))0 1384 y Fi(2)81 b Fj(Get)34 b(the)g(curren)m(t)g(system) f(date)i(and)e(time)g(string)g(\('YYYY-MM-DDThh:mm:ss'\).)53 b(The)33 b(time)h(will)d(b)s(e)227 1497 y(in)25 b(UTC/GMT)h(if)f(a)m(v) -5 b(ailable,)26 b(as)h(indicated)d(b)m(y)i(a)g(returned)f(timeref)g(v) -5 b(alue)26 b(=)f(0.)40 b(If)26 b(the)g(returned)e(v)-5 b(alue)227 1610 y(of)31 b(timeref)f(=)h(1)g(then)f(this)g(indicates)f (that)j(it)e(w)m(as)h(not)g(p)s(ossible)d(to)j(con)m(v)m(ert)i(the)d (lo)s(cal)g(time)h(to)g(UTC,)227 1722 y(and)f(th)m(us)g(the)h(lo)s(cal) e(time)h(w)m(as)h(returned.)95 1967 y Fe(int)47 b (fits_get_system_time/ffgst)o(m)286 2080 y(\(>)h(char)e(*datestr,)f (int)95 b(*timeref,)45 b(int)i(*status\))0 2325 y Fi(3)81 b Fj(Construct)26 b(a)i(date)g(string)e(from)h(the)g(input)e(date)j(v) -5 b(alues.)39 b(If)27 b(the)g(y)m(ear)h(is)f(b)s(et)m(w)m(een)g(1900)i (and)e(1998,)j(inclu-)227 2438 y(siv)m(e,)37 b(then)d(the)i(returned)d (date)j(string)e(will)e(ha)m(v)m(e)37 b(the)e(old)f(FITS)g(format)i (\('dd/mm/yy'\),)h(otherwise)227 2551 y(the)32 b(date)f(string)f(will)f (ha)m(v)m(e)j(the)g(new)e(FITS)h(format)g(\('YYYY-MM-DD'\).)36 b(Use)31 b(\014ts)p 3229 2551 28 4 v 33 w(time2str)g(instead)227 2664 y(to)g(alw)m(a)m(ys)g(return)f(a)g(date)h(string)f(using)f(the)h (new)g(FITS)g(format.)95 2909 y Fe(int)47 b(fits_date2str/ffdt2s)286 3022 y(\(int)g(year,)f(int)h(month,)f(int)h(day,)g(>)g(char)g (*datestr,)e(int)i(*status\))0 3267 y Fi(4)81 b Fj(Construct)34 b(a)i(new-format)f(date)h(+)f(time)g(string)f (\('YYYY-MM-DDThh:mm:ss.ddd...'\).)57 b(If)34 b(the)i(y)m(ear,)227 3379 y(mon)m(th,)d(and)e(da)m(y)h(v)-5 b(alues)31 b(all)g(=)g(0)h(then) g(only)f(the)h(time)f(is)g(enco)s(ded)g(with)g(format)h ('hh:mm:ss.ddd...'.)227 3492 y(The)j(decimals)f(parameter)i(sp)s (eci\014es)d(ho)m(w)j(man)m(y)f(decimal)f(places)h(of)g(fractional)g (seconds)g(to)h(include)227 3605 y(in)29 b(the)i(string.)40 b(If)29 b(`decimals')h(is)g(negativ)m(e,)h(then)g(only)e(the)i(date)g (will)c(b)s(e)j(return)f(\('YYYY-MM-DD'\).)95 3850 y Fe(int)47 b(fits_time2str/fftm2s)286 3963 y(\(int)g(year,)f(int)h (month,)f(int)h(day,)g(int)g(hour,)f(int)h(minute,)f(double)g(second,) 286 4076 y(int)h(decimals,)f(>)h(char)g(*datestr,)e(int)i(*status\))0 4321 y Fi(5)81 b Fj(Return)44 b(the)g(date)i(as)f(read)f(from)h(the)g (input)d(string,)48 b(where)c(the)h(string)f(ma)m(y)h(b)s(e)f(in)g (either)g(the)h(old)227 4434 y(\('dd/mm/yy'\))29 b(or)f(new)f (\('YYYY-MM-DDThh:mm:ss')k(or)d('YYYY-MM-DD'\))j(FITS)d(format.)40 b(Null)227 4547 y(p)s(oin)m(ters)30 b(ma)m(y)g(b)s(e)g(supplied)d(for)j (an)m(y)h(un)m(w)m(an)m(ted)g(output)f(date)h(parameters.)95 4792 y Fe(int)47 b(fits_str2date/ffs2dt)286 4904 y(\(char)g(*datestr,)e (>)i(int)g(*year,)f(int)h(*month,)f(int)h(*day,)f(int)h(*status\))0 5149 y Fi(6)81 b Fj(Return)30 b(the)h(date)h(and)f(time)g(as)g(read)g (from)g(the)h(input)d(string,)h(where)h(the)h(string)e(ma)m(y)i(b)s(e)e (in)g(either)h(the)227 5262 y(old)d(or)g(new)g(FITS)g(format.)40 b(The)28 b(returned)f(hours,)h(min)m(utes,)g(and)g(seconds)g(v)-5 b(alues)28 b(will)d(b)s(e)j(set)h(to)g(zero)227 5375 y(if)j(the)i(input)d(string)h(do)s(es)h(not)h(include)d(the)i(time)g (\('dd/mm/yy')g(or)h('YYYY-MM-DD'\))j(.)c(Similarly)-8 b(,)227 5488 y(the)36 b(returned)e(y)m(ear,)j(mon)m(th,)g(and)d(date)i (v)-5 b(alues)35 b(will)d(b)s(e)j(set)h(to)g(zero)g(if)e(the)h(date)h (is)e(not)i(included)c(in)227 5601 y(the)d(input)e(string)h (\('hh:mm:ss.ddd...'\).)40 b(Null)27 b(p)s(oin)m(ters)g(ma)m(y)j(b)s(e) e(supplied)d(for)k(an)m(y)g(un)m(w)m(an)m(ted)g(output)227 5714 y(date)i(and)f(time)g(parameters.)p eop %%Page: 56 64 56 63 bop 0 299 a Fj(56)1379 b Fh(CHAPTER)30 b(5.)71 b(BASIC)30 b(CFITSIO)f(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)95 555 y Fe(int)47 b(fits_str2time/ffs2tm)286 668 y(\(char)g(*datestr,)e (>)i(int)g(*year,)f(int)h(*month,)f(int)h(*day,)f(int)h(*hour,)286 781 y(int)g(*minute,)f(double)g(*second,)f(int)i(*status\))0 1068 y Fd(5.8.3)112 b(General)38 b(Utilit)m(y)c(Routines)0 1286 y Fj(The)c(follo)m(wing)f(utilit)m(y)f(routines)i(ma)m(y)h(b)s(e)e (useful)g(for)h(certain)g(applications.)0 1520 y Fi(1)81 b Fj(Return)30 b(the)h(revision)e(n)m(um)m(b)s(er)h(of)h(the)g(CFITSIO) f(library)-8 b(.)40 b(The)31 b(revision)e(n)m(um)m(b)s(er)h(will)e(b)s (e)i(incremen)m(ted)227 1633 y(with)f(eac)m(h)j(new)e(release)g(of)h (CFITSIO.)95 1867 y Fe(float)47 b(fits_get_version)c(/)48 b(ffvers)e(\()h(>)h(float)e(*version\))0 2100 y Fi(2)81 b Fj(W)-8 b(rite)33 b(an)h(80-c)m(haracter)i(message)e(to)g(the)g (CFITSIO)e(error)h(stac)m(k.)51 b(Application)31 b(programs)i(should)f (not)227 2213 y(normally)d(write)g(to)j(the)e(stac)m(k,)i(but)e(there)g (ma)m(y)h(b)s(e)f(some)h(situations)e(where)h(this)f(is)h(desirable.)95 2447 y Fe(void)47 b(fits_write_errmsg)c(/)48 b(ffpmsg)e(\(char)g (*err_msg\))0 2681 y Fi(3)81 b Fj(Con)m(v)m(ert)31 b(a)g(c)m(haracter)h (string)d(to)i(upp)s(ercase)e(\(op)s(erates)j(in)d(place\).)95 2914 y Fe(void)47 b(fits_uppercase)d(/)j(ffupch)g(\(char)f(*string\))0 3148 y Fi(4)81 b Fj(Compare)43 b(the)i(input)d(template)i(string)f (against)h(the)h(reference)f(string)f(to)i(see)g(if)e(they)h(matc)m(h.) 82 b(The)227 3261 y(template)35 b(string)f(ma)m(y)h(con)m(tain)f (wildcard)e(c)m(haracters:)51 b('*')35 b(will)d(matc)m(h)j(an)m(y)g (sequence)g(of)f(c)m(haracters)227 3374 y(\(including)26 b(zero)k(c)m(haracters\))h(and)d('\045')i(will)c(matc)m(h)k(an)m(y)f (single)f(c)m(haracter)j(in)c(the)j(reference)f(string.)39 b(If)227 3487 y(casesen)25 b(=)f(CASESEN)f(=)h(TR)m(UE)h(then)e(the)i (matc)m(h)g(will)d(b)s(e)h(case)j(sensitiv)m(e,)f(otherwise)e(the)i (case)g(of)g(the)227 3600 y(letters)h(will)d(b)s(e)i(ignored)f(if)h (casesen)h(=)f(CASEINSEN)f(=)h(F)-10 b(ALSE.)25 b(The)g(returned)g(MA) -8 b(TCH)25 b(parameter)227 3713 y(will)30 b(b)s(e)h(TR)m(UE)i(if)e (the)h(2)h(strings)e(matc)m(h,)j(and)d(EXA)m(CT)h(will)e(b)s(e)h(TR)m (UE)i(if)e(the)h(matc)m(h)h(is)f(exact)h(\(i.e.,)227 3826 y(if)27 b(no)h(wildcard)e(c)m(haracters)j(w)m(ere)g(used)e(in)f (the)j(matc)m(h\).)41 b(Both)28 b(strings)f(m)m(ust)h(b)s(e)f(68)i(c)m (haracters)h(or)e(less)227 3938 y(in)h(length.)95 4172 y Fe(void)47 b(fits_compare_str)c(/)48 b(ffcmps)334 4285 y(\(char)e(*templt,)g(char)h(*string,)e(int)i(casesen,)f(>)h(int)g (*match,)f(int)h(*exact\))0 4519 y Fi(5)81 b Fj(Split)28 b(a)k(string)e(con)m(taining)g(a)i(list)d(of)i(names)g(\(t)m(ypically)g (\014le)f(names)h(or)g(column)e(names\))j(in)m(to)f(individual)227 4632 y(name)23 b(tok)m(ens)g(b)m(y)g(a)g(sequence)g(of)g(calls)e(to)j (\014ts)p 1814 4632 28 4 v 32 w(split)p 2020 4632 V 31 w(names.)38 b(The)22 b(names)h(in)e(the)i(list)e(m)m(ust)h(b)s(e)g (delimited)227 4745 y(b)m(y)45 b(a)f(comma)i(and/or)e(spaces.)83 b(This)43 b(routine)g(ignores)h(spaces)h(and)f(commas)h(that)g(o)s (ccur)f(within)227 4857 y(paren)m(theses,)36 b(brac)m(k)m(ets,)h(or)e (curly)e(brac)m(k)m(ets.)54 b(It)35 b(also)f(strips)f(an)m(y)i(leading) e(and)h(trailing)e(blanks)h(from)227 4970 y(the)e(returned)e(name.)227 5116 y(This)g(routine)g(is)h(similar)d(to)k(the)g(ANSI)f(C)g('strtok')h (function:)227 5262 y(The)37 b(\014rst)f(call)g(to)i(\014ts)p 1033 5262 V 32 w(split)p 1239 5262 V 31 w(names)f(has)g(a)g(non-n)m (ull)d(input)h(string.)60 b(It)37 b(\014nds)e(the)i(\014rst)f(name)h (in)f(the)227 5375 y(string)25 b(and)g(terminates)g(it)h(b)m(y)f(o)m(v) m(erwriting)g(the)h(next)g(c)m(haracter)h(of)f(the)g(string)e(with)h(a) h(n)m(ull)d(terminator)227 5488 y(and)31 b(returns)g(a)h(p)s(oin)m(ter) e(to)j(the)e(name.)45 b(Eac)m(h)32 b(subsequen)m(t)f(call,)h(indicated) e(b)m(y)h(a)h(NULL)g(v)-5 b(alue)31 b(of)h(the)227 5601 y(input)e(string,)i(returns)f(the)h(next)h(name,)f(searc)m(hing)g(from) g(just)g(past)g(the)g(end)f(of)i(the)f(previous)f(name.)227 5714 y(It)g(returns)e(NULL)h(when)g(no)g(further)f(names)h(are)h (found.)p eop %%Page: 57 65 57 64 bop 0 299 a Fh(5.8.)72 b(UTILITY)30 b(R)m(OUTINES)2693 b Fj(57)143 555 y Fe(char)47 b(*fits_split_names\(char)42 b(*namelist\))0 797 y Fj(The)30 b(follo)m(wing)f(example)h(sho)m(ws)g (ho)m(w)g(a)h(string)e(w)m(ould)h(b)s(e)f(split)g(in)m(to)h(3)h(names:) 191 1039 y Fe(myfile[1][bin)44 b(\(x,y\)=4],)h(file2.fits)93 b(file3.fits)191 1152 y(^^^^^^^^^^^^^^^^^^^^^^)c(^^^^^^^^^^)k (^^^^^^^^^^)382 1264 y(1st)47 b(name)619 b(2nd)47 b(name)190 b(3rd)47 b(name)0 1506 y Fi(6)81 b Fj(T)-8 b(est)34 b(that)g(the)g(k)m (eyw)m(ord)g(name)f(con)m(tains)h(only)e(legal)i(c)m(haracters)h (\(A-Z,0-9,)h(h)m(yphen,)d(and)g(underscore\))227 1619 y(or)e(that)g(the)f(k)m(eyw)m(ord)h(record)f(con)m(tains)h(only)e (legal)h(prin)m(table)f(ASCI)s(I)g(c)m(haracters)95 1861 y Fe(int)47 b(fits_test_keyword)c(/)48 b(fftkey)e(\(char)g(*keyname,)g (>)h(int)g(*status\))95 2087 y(int)g(fits_test_record)d(/)j(fftrec)f (\(char)h(*card,)f(>)h(int)g(*status\))0 2328 y Fi(7)81 b Fj(T)-8 b(est)25 b(whether)f(the)h(curren)m(t)f(header)h(con)m(tains) f(an)m(y)h(NULL)g(\(ASCI)s(I)e(0\))j(c)m(haracters.)40 b(These)24 b(c)m(haracters)j(are)227 2441 y(illegal)33 b(in)g(the)i(header,)g(but)f(they)g(will)e(go)j(undetected)g(b)m(y)f (most)h(of)g(the)f(CFITSIO)f(k)m(eyw)m(ord)i(header)227 2554 y(routines,)28 b(b)s(ecause)g(the)h(n)m(ull)d(is)h(in)m(terpreted) g(as)i(the)f(normal)f(end-of-string)h(terminator.)40 b(This)26 b(routine)227 2667 y(returns)i(the)g(p)s(osition)f(of)i(the)g (\014rst)f(n)m(ull)e(c)m(haracter)k(in)e(the)g(header,)h(or)g(zero)g (if)f(there)h(are)g(no)f(n)m(ulls.)38 b(F)-8 b(or)227 2780 y(example)36 b(a)g(returned)f(v)-5 b(alue)36 b(of)g(110)h(w)m (ould)e(indicate)g(that)i(the)f(\014rst)f(NULL)h(is)f(lo)s(cated)h(in)f (the)h(30th)227 2893 y(c)m(haracter)28 b(of)f(the)g(second)f(k)m(eyw)m (ord)h(in)e(the)i(header)f(\(recall)g(that)h(eac)m(h)h(header)e(record) h(is)e(80)i(c)m(haracters)227 3006 y(long\).)44 b(Note)33 b(that)f(this)f(is)f(one)i(of)g(the)g(few)f(CFITSIO)f(routines)g(in)h (whic)m(h)f(the)i(returned)e(v)-5 b(alue)31 b(is)g(not)227 3119 y(necessarily)f(equal)f(to)j(the)e(status)h(v)-5 b(alue\).)95 3360 y Fe(int)47 b(fits_null_check)d(/)j(ffnchk)g(\(char)f (*card,)g(>)h(int)g(*status\))0 3602 y Fi(8)81 b Fj(P)m(arse)25 b(a)g(header)g(k)m(eyw)m(ord)g(record)g(and)f(return)g(the)h(name)g(of) g(the)g(k)m(eyw)m(ord,)i(and)d(the)h(length)g(of)g(the)g(name.)227 3715 y(The)34 b(k)m(eyw)m(ord)h(name)f(normally)f(o)s(ccupies)g(the)i (\014rst)e(8)i(c)m(haracters)g(of)g(the)f(record,)i(except)f(under)e (the)227 3828 y(HIERAR)m(CH)e(con)m(v)m(en)m(tion)g(where)f(the)h(name) f(can)h(b)s(e)f(up)f(to)i(70)g(c)m(haracters)h(in)d(length.)95 4070 y Fe(int)47 b(fits_get_keyname)d(/)j(ffgknm)286 4182 y(\(char)g(*card,)f(>)h(char)g(*keyname,)e(int)i(*keylength,)e (int)i(*status\))0 4424 y Fi(9)81 b Fj(P)m(arse)29 b(a)h(header)f(k)m (eyw)m(ord)h(record,)f(returning)f(the)h(v)-5 b(alue)29 b(\(as)h(a)f(literal)f(c)m(haracter)j(string\))d(and)h(commen)m(t)227 4537 y(strings.)39 b(If)27 b(the)g(k)m(eyw)m(ord)h(has)f(no)g(v)-5 b(alue)27 b(\(columns)f(9-10)j(not)f(equal)e(to)i('=)g('\),)g(then)f(a) h(n)m(ull)d(v)-5 b(alue)27 b(string)227 4650 y(is)j(returned)f(and)h (the)g(commen)m(t)i(string)d(is)g(set)i(equal)f(to)h(column)e(9)i(-)g (80)g(of)g(the)f(input)f(string.)95 4892 y Fe(int)47 b(fits_parse_value)d(/)j(ffpsvc)286 5005 y(\(char)g(*card,)f(>)h(char)g (*value,)f(char)g(*comment,)g(int)h(*status\))0 5246 y Fi(10)f Fj(Construct)26 b(an)h(arra)m(y)g(indexed)e(k)m(eyw)m(ord)i (name)f(\(R)m(OOT)g(+)h(nnn\).)38 b(This)25 b(routine)g(app)s(ends)g (the)i(sequence)227 5359 y(n)m(um)m(b)s(er)i(to)i(the)g(ro)s(ot)g (string)e(to)i(create)h(a)f(k)m(eyw)m(ord)g(name)f(\(e.g.,)i('NAXIS')f (+)f(2)h(=)f('NAXIS2'\))95 5601 y Fe(int)47 b(fits_make_keyn)d(/)k (ffkeyn)286 5714 y(\(char)f(*keyroot,)e(int)i(value,)f(>)h(char)g (*keyname,)e(int)i(*status\))p eop %%Page: 58 66 58 65 bop 0 299 a Fj(58)1379 b Fh(CHAPTER)30 b(5.)71 b(BASIC)30 b(CFITSIO)f(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)0 555 y Fi(11)46 b Fj(Construct)41 b(a)h(sequence)f(k)m(eyw)m(ord)h(name) g(\(n)f(+)g(R)m(OOT\).)g(This)f(routine)g(concatenates)k(the)e (sequence)227 668 y(n)m(um)m(b)s(er)20 b(to)j(the)e(fron)m(t)h(of)g (the)f(ro)s(ot)h(string)f(to)h(create)h(a)f(k)m(eyw)m(ord)g(name)g (\(e.g.,)j(1)d(+)f('CTYP')g(=)g('1CTYP'\))95 1045 y Fe(int)47 b(fits_make_nkey)d(/)k(ffnkey)286 1158 y(\(int)f(value,)f(char)h (*keyroot,)e(>)i(char)g(*keyname,)e(int)i(*status\))0 1422 y Fi(12)f Fj(Determine)40 b(the)h(data)f(t)m(yp)s(e)h(of)f(a)h(k)m (eyw)m(ord)f(v)-5 b(alue)40 b(string.)69 b(This)38 b(routine)i(parses)f (the)i(k)m(eyw)m(ord)f(v)-5 b(alue)227 1535 y(string)27 b(to)i(determine)e(its)g(data)i(t)m(yp)s(e.)40 b(Returns)27 b('C',)h('L',)h('I',)f('F')h(or)f('X',)g(for)g(c)m(haracter)i(string,)d (logical,)227 1648 y(in)m(teger,)k(\015oating)g(p)s(oin)m(t,)e(or)i (complex,)f(resp)s(ectiv)m(ely)-8 b(.)95 1912 y Fe(int)47 b(fits_get_keytype)d(/)j(ffdtyp)286 2025 y(\(char)g(*value,)f(>)h(char) g(*dtype,)e(int)i(*status\))0 2288 y Fi(13)f Fj(Return)35 b(the)g(class)g(of)h(an)f(input)f(header)h(record.)56 b(The)35 b(record)g(is)f(classi\014ed)g(in)m(to)i(one)f(of)h(the)f (follo)m(wing)227 2401 y(categories)c(\(the)f(class)f(v)-5 b(alues)29 b(are)g(de\014ned)f(in)g(\014tsio.h\).)40 b(Note)31 b(that)f(this)e(is)g(one)i(of)f(the)g(few)g(CFITSIO)227 2514 y(routines)h(that)g(do)s(es)h(not)f(return)f(a)i(status)g(v)-5 b(alue.)334 2778 y Fe(Class)94 b(Value)619 b(Keywords)95 2891 y(TYP_STRUC_KEY)92 b(10)j(SIMPLE,)46 b(BITPIX,)g(NAXIS,)g(NAXISn,) g(EXTEND,)g(BLOCKED,)1002 3004 y(GROUPS,)g(PCOUNT,)g(GCOUNT,)g(END)1002 3117 y(XTENSION,)g(TFIELDS,)f(TTYPEn,)h(TBCOLn,)g(TFORMn,)g(THEAP,)1002 3230 y(and)h(the)g(first)f(4)i(COMMENT)e(keywords)f(in)i(the)g(primary) f(array)1002 3343 y(that)h(define)f(the)h(FITS)g(format.)95 3456 y(TYP_CMPRS_KEY)92 b(20)j(The)47 b(experimental)e(keywords)g(used) i(in)g(the)g(compressed)1002 3569 y(image)g(format)f(ZIMAGE,)g (ZCMPTYPE,)f(ZNAMEn,)h(ZVALn,)1002 3681 y(ZTILEn,)g(ZBITPIX,)g (ZNAXISn,)f(ZSCALE,)h(ZZERO,)g(ZBLANK)95 3794 y(TYP_SCAL_KEY)140 b(30)95 b(BSCALE,)46 b(BZERO,)g(TSCALn,)g(TZEROn)95 3907 y(TYP_NULL_KEY)140 b(40)95 b(BLANK,)46 b(TNULLn)95 4020 y(TYP_DIM_KEY)188 b(50)95 b(TDIMn)95 4133 y(TYP_RANG_KEY)140 b(60)95 b(TLMINn,)46 b(TLMAXn,)g(TDMINn,)g(TDMAXn,)g(DATAMIN,)f (DATAMAX)95 4246 y(TYP_UNIT_KEY)140 b(70)95 b(BUNIT,)46 b(TUNITn)95 4359 y(TYP_DISP_KEY)140 b(80)95 b(TDISPn)95 4472 y(TYP_HDUID_KEY)d(90)j(EXTNAME,)46 b(EXTVER,)g(EXTLEVEL,)f (HDUNAME,)g(HDUVER,)h(HDULEVEL)95 4585 y(TYP_CKSUM_KEY)f(100)94 b(CHECKSUM,)46 b(DATASUM)95 4698 y(TYP_WCS_KEY)141 b(110)94 b(CTYPEn,)46 b(CUNITn,)g(CRVALn,)g(CRPIXn,)g(CROTAn,)f(CDELTn)1002 4811 y(CDj_is,)h(PVj_ms,)g(LONPOLEs,)f(LATPOLEs)1002 4924 y(TCTYPn,)h(TCTYns,)g(TCUNIn,)g(TCUNns,)g(TCRVLn,)f(TCRVns,)h (TCRPXn,)1002 5036 y(TCRPks,)g(TCDn_k,)g(TCn_ks,)g(TPVn_m,)g(TPn_ms,)f (TCDLTn,)h(TCROTn)1002 5149 y(jCTYPn,)g(jCTYns,)g(jCUNIn,)g(jCUNns,)g (jCRVLn,)f(jCRVns,)h(iCRPXn,)1002 5262 y(iCRPns,)g(jiCDn,)94 b(jiCDns,)46 b(jPVn_m,)g(jPn_ms,)f(jCDLTn,)h(jCROTn)1002 5375 y(\(i,j,m,n)g(are)h(integers,)e(s)i(is)h(any)f(letter\))95 5488 y(TYP_REFSYS_KEY)d(120)j(EQUINOXs,)f(EPOCH,)g(MJD-OBSs,)f (RADECSYS,)g(RADESYSs)95 5601 y(TYP_COMM_KEY)140 b(130)47 b(COMMENT,)f(HISTORY,)f(\(blank)h(keyword\))95 5714 y(TYP_CONT_KEY)140 b(140)47 b(CONTINUE)p eop %%Page: 59 67 59 66 bop 0 299 a Fh(5.8.)72 b(UTILITY)30 b(R)m(OUTINES)2693 b Fj(59)95 555 y Fe(TYP_USER_KEY)140 b(150)47 b(all)g(other)g(keywords) 95 781 y(int)g(fits_get_keyclass)c(/)48 b(ffgkcl)e(\(char)g(*card\))0 1034 y Fi(14)g Fj(P)m(arse)28 b(the)g('TF)m(ORM')g(binary)e(table)h (column)g(format)g(string.)39 b(This)26 b(routine)g(parses)h(the)h (input)e(TF)m(ORM)227 1147 y(c)m(haracter)38 b(string)c(and)h(returns)g (the)g(in)m(teger)h(data)h(t)m(yp)s(e)f(co)s(de,)h(the)f(rep)s(eat)g (coun)m(t)g(of)g(the)f(\014eld,)h(and,)227 1260 y(in)e(the)g(case)i(of) f(c)m(haracter)h(string)e(\014elds,)g(the)h(length)f(of)h(the)g(unit)e (string.)53 b(See)34 b(App)s(endix)e(B)j(for)g(the)227 1373 y(allo)m(w)m(ed)k(v)-5 b(alues)37 b(for)i(the)f(returned)g(t)m(yp) s(eco)s(de)h(parameter.)65 b(A)39 b(n)m(ull)d(p)s(oin)m(ter)i(ma)m(y)h (b)s(e)f(giv)m(en)g(for)h(an)m(y)227 1486 y(output)30 b(parameters)h(that)g(are)g(not)f(needed.)143 1739 y Fe(int)47 b(fits_binary_tform)c(/)48 b(ffbnfm)334 1852 y(\(char)e(*tform,)g(>)i(int)f(*typecode,)e(long)h(*repeat,)g(long)g (*width,)382 1965 y(int)h(*status\))0 2218 y Fi(15)f Fj(P)m(arse)38 b(the)f('TF)m(ORM')h(k)m(eyw)m(ord)g(v)-5 b(alue)36 b(that)i(de\014nes)e(the)h(column)f(format)i(in)d(an)i(ASCI)s (I)f(table.)61 b(This)227 2331 y(routine)28 b(parses)h(the)g(input)e (TF)m(ORM)i(c)m(haracter)h(string)e(and)h(returns)e(the)i(data)h(t)m (yp)s(e)f(co)s(de,)h(the)f(width)227 2443 y(of)f(the)f(column,)g(and)g (\(if)g(it)g(is)f(a)i(\015oating)f(p)s(oin)m(t)g(column\))f(the)i(n)m (um)m(b)s(er)e(of)h(decimal)g(places)g(to)h(the)f(righ)m(t)227 2556 y(of)39 b(the)f(decimal)f(p)s(oin)m(t.)64 b(The)38 b(returned)f(data)i(t)m(yp)s(e)f(co)s(des)g(are)h(the)g(same)f(as)h (for)f(the)g(binary)f(table,)227 2669 y(with)25 b(the)i(follo)m(wing)e (additional)f(rules:)37 b(in)m(teger)27 b(columns)e(that)i(are)f(b)s (et)m(w)m(een)h(1)g(and)f(4)g(c)m(haracters)i(wide)227 2782 y(are)i(de\014ned)e(to)j(b)s(e)d(short)i(in)m(tegers)f(\(co)s(de)h (=)g(TSHOR)-8 b(T\).)29 b(Wider)f(in)m(teger)i(columns)e(are)i (de\014ned)e(to)j(b)s(e)227 2895 y(regular)38 b(in)m(tegers)g(\(co)s (de)h(=)f(TLONG\).)h(Similarly)-8 b(,)37 b(Fixed)h(decimal)f(p)s(oin)m (t)g(columns)g(\(with)h(TF)m(ORM)227 3008 y(=)d('Fw.d'\))g(are)h (de\014ned)d(to)j(b)s(e)e(single)g(precision)f(reals)i(\(co)s(de)g(=)g (TFLO)m(A)-8 b(T\))35 b(if)f(w)h(is)f(b)s(et)m(w)m(een)h(1)h(and)227 3121 y(7)42 b(c)m(haracters)h(wide,)g(inclusiv)m(e.)72 b(Wider)40 b('F')i(columns)e(will)f(return)h(a)i(double)e(precision)g (data)i(co)s(de)227 3234 y(\(=)32 b(TDOUBLE\).)h('Ew.d')f(format)g (columns)f(will)e(ha)m(v)m(e)34 b(dataco)s(de)f(=)e(TFLO)m(A)-8 b(T,)33 b(and)e('Dw.d')i(format)227 3347 y(columns)44 b(will)f(ha)m(v)m(e)k(dataco)s(de)f(=)f(TDOUBLE.)g(A)h(n)m(ull)d(p)s (oin)m(ter)i(ma)m(y)g(b)s(e)g(giv)m(en)h(for)f(an)m(y)g(output)227 3460 y(parameters)31 b(that)g(are)g(not)f(needed.)95 3713 y Fe(int)47 b(fits_ascii_tform)d(/)j(ffasfm)286 3826 y(\(char)g(*tform,)f(>)h(int)g(*typecode,)e(long)i(*width,)e(int)i (*decimals,)334 3939 y(int)g(*status\))0 4192 y Fi(16)f Fj(Calculate)30 b(the)h(starting)f(column)g(p)s(ositions)e(and)i(total) h(ASCI)s(I)e(table)i(width)d(based)j(on)f(the)h(input)d(arra)m(y)227 4304 y(of)f(ASCI)s(I)e(table)h(TF)m(ORM)h(v)-5 b(alues.)39 b(The)26 b(SP)-8 b(A)m(CE)27 b(input)d(parameter)j(de\014nes)f(ho)m(w)h (man)m(y)f(blank)g(spaces)227 4417 y(to)40 b(lea)m(v)m(e)h(b)s(et)m(w)m (een)f(eac)m(h)g(column)f(\(it)g(is)f(recommended)h(to)h(ha)m(v)m(e)h (one)e(space)h(b)s(et)m(w)m(een)g(columns)e(for)227 4530 y(b)s(etter)31 b(h)m(uman)e(readabilit)m(y\).)95 4783 y Fe(int)47 b(fits_get_tbcol)d(/)k(ffgabc)286 4896 y(\(int)f(tfields,)f (char)g(**tform,)g(int)h(space,)f(>)h(long)g(*rowlen,)334 5009 y(long)g(*tbcol,)f(int)g(*status\))0 5262 y Fi(17)g Fj(P)m(arse)27 b(a)g(template)g(header)f(record)g(and)g(return)g(a)g (formatted)h(80-c)m(haracter)j(string)25 b(suitable)g(for)h(app)s(end-) 227 5375 y(ing)39 b(to)g(\(or)h(deleting)e(from\))h(a)g(FITS)g(header)g (\014le.)66 b(This)37 b(routine)h(is)g(useful)g(for)g(parsing)g(lines)f (from)227 5488 y(an)c(ASCI)s(I)f(template)h(\014le)f(and)h (reformatting)g(them)g(in)m(to)g(legal)g(FITS)f(header)h(records.)49 b(The)32 b(format-)227 5601 y(ted)i(string)f(ma)m(y)h(then)f(b)s(e)g (passed)h(to)g(the)g(\014ts)p 1880 5601 28 4 v 32 w(write)p 2115 5601 V 32 w(record,)h(\013mcrd,)f(or)g(\014ts)p 3007 5601 V 32 w(delete)p 3271 5601 V 33 w(k)m(ey)h(routines)d(to)227 5714 y(app)s(end)d(or)h(mo)s(dify)f(a)i(FITS)e(header)h(record.)p eop %%Page: 60 68 60 67 bop 0 299 a Fj(60)1379 b Fh(CHAPTER)30 b(5.)71 b(BASIC)30 b(CFITSIO)f(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)95 555 y Fe(int)47 b(fits_parse_template)c(/)k(ffgthd)286 668 y(\(char)g(*templt,)e(>)j(char)e(*card,)g(int)h(*keytype,)f(int)h (*status\))0 932 y Fj(The)31 b(input)f(templt)h(c)m(haracter)i(string)e (generally)g(should)e(con)m(tain)j(3)g(tok)m(ens:)44 b(\(1\))33 b(the)f(KEYNAME,)g(\(2\))h(the)0 1045 y(V)-10 b(ALUE,)37 b(and)f(\(3\))i(the)f(COMMENT)g(string.)58 b(The)37 b(TEMPLA)-8 b(TE)36 b(string)g(m)m(ust)g(adhere)h(to)h(the)e (follo)m(wing)0 1158 y(format:)0 1421 y Fi(-)80 b Fj(The)32 b(KEYNAME)h(tok)m(en)h(m)m(ust)f(b)s(egin)e(in)h(columns)f(1-8)j(and)e (b)s(e)g(a)h(maxim)m(um)f(of)h(8)g(c)m(haracters)h(long.)48 b(A)227 1534 y(legal)28 b(FITS)g(k)m(eyw)m(ord)h(name)f(ma)m(y)h(only)e (con)m(tain)i(the)g(c)m(haracters)g(A-Z,)g(0-9,)h(and)e('-')h(\(min)m (us)e(sign\))h(and)227 1647 y(underscore.)40 b(This)26 b(routine)i(will)e(automatically)i(con)m(v)m(ert)i(an)m(y)f(lo)m(w)m (ercase)h(c)m(haracters)g(to)g(upp)s(ercase)d(in)227 1760 y(the)k(output)f(string.)41 b(If)30 b(the)h(\014rst)f(8)h(c)m (haracters)h(of)f(the)g(template)g(line)e(are)i(blank)e(then)i(the)g (remainder)227 1873 y(of)g(the)f(line)f(is)h(considered)f(to)i(b)s(e)f (a)g(FITS)g(commen)m(t)h(\(with)f(a)h(blank)e(k)m(eyw)m(ord)h(name\).)0 2137 y Fi(-)80 b Fj(The)26 b(V)-10 b(ALUE)26 b(tok)m(en)h(m)m(ust)e(b)s (e)h(separated)g(from)f(the)i(KEYNAME)f(tok)m(en)h(b)m(y)f(one)g(or)g (more)g(spaces)g(and/or)227 2250 y(an)g('=')g(c)m(haracter.)41 b(The)25 b(data)h(t)m(yp)s(e)g(of)g(the)g(V)-10 b(ALUE)26 b(tok)m(en)g(\(n)m(umeric,)g(logical,)h(or)f(c)m(haracter)h(string\))e (is)227 2363 y(automatically)32 b(determined)e(and)i(the)g(output)f (CARD)h(string)f(is)g(formatted)h(accordingly)-8 b(.)45 b(The)31 b(v)-5 b(alue)227 2476 y(tok)m(en)34 b(ma)m(y)f(b)s(e)f (forced)g(to)i(b)s(e)e(in)m(terpreted)f(as)i(a)g(string)f(\(e.g.)48 b(if)32 b(it)g(is)f(a)i(string)f(of)g(n)m(umeric)g(digits\))f(b)m(y)227 2588 y(enclosing)f(it)g(in)f(single)g(quotes.)0 2852 y Fi(-)80 b Fj(The)28 b(COMMENT)g(tok)m(en)h(is)e(optional,)h(but)g(if) f(presen)m(t)h(m)m(ust)g(b)s(e)g(separated)g(from)g(the)g(V)-10 b(ALUE)29 b(tok)m(en)g(b)m(y)227 2965 y(at)i(least)g(one)g(blank)e (space)i(and)e(a)i('/')g(c)m(haracter.)0 3229 y Fi(-)80 b Fj(One)29 b(exception)g(to)g(the)g(ab)s(o)m(v)m(e)i(rules)c(is)h (that)h(if)f(the)h(\014rst)g(non-blank)e(c)m(haracter)j(in)e(the)h (\014rst)f(8)h(c)m(haracters)227 3342 y(of)24 b(the)h(template)f (string)f(is)g(a)h(min)m(us)f(sign)g(\('-'\))i(follo)m(w)m(ed)f(b)m(y)g (a)g(single)f(tok)m(en,)j(or)e(a)h(single)d(tok)m(en)j(follo)m(w)m(ed) 227 3455 y(b)m(y)k(an)g(equal)g(sign,)g(then)g(it)f(is)h(in)m (terpreted)f(as)i(the)f(name)g(of)h(a)f(k)m(eyw)m(ord)h(whic)m(h)e(is)g (to)i(b)s(e)e(deleted)h(from)227 3568 y(the)i(FITS)e(header.)0 3831 y Fi(-)80 b Fj(The)32 b(second)g(exception)g(is)f(that)i(if)e(the) h(template)g(string)f(starts)i(with)d(a)j(min)m(us)d(sign)h(and)g(is)g (follo)m(w)m(ed)h(b)m(y)227 3944 y(2)h(tok)m(ens)g(\(without)f(an)g (equals)g(sign)g(b)s(et)m(w)m(een)h(them\))f(then)g(the)h(second)f(tok) m(en)i(is)d(in)m(terpreted)h(as)h(the)227 4057 y(new)f(name)h(for)f (the)h(k)m(eyw)m(ord)g(sp)s(eci\014ed)e(b)m(y)i(\014rst)f(tok)m(en.)48 b(In)32 b(this)f(case)j(the)f(old)f(k)m(eyw)m(ord)h(name)f(\(\014rst) 227 4170 y(tok)m(en\))c(is)d(returned)f(in)h(c)m(haracters)i(1-8)g(of)g (the)f(returned)e(CARD)j(string,)f(and)f(the)h(new)f(k)m(eyw)m(ord)i (name)227 4283 y(\(the)35 b(second)e(tok)m(en\))j(is)d(returned)f(in)h (c)m(haracters)i(41-48)h(of)e(the)g(returned)e(CARD)i(string.)50 b(These)34 b(old)227 4396 y(and)i(new)f(names)h(ma)m(y)h(then)f(b)s(e)f (passed)g(to)i(the)f(\013mnam)g(routine)f(whic)m(h)g(will)e(c)m(hange)k (the)f(k)m(eyw)m(ord)227 4509 y(name.)0 4773 y(The)30 b(k)m(eyt)m(yp)s(e)h(output)f(parameter)h(indicates)e(ho)m(w)i(the)f (returned)g(CARD)g(string)f(should)g(b)s(e)g(in)m(terpreted:)382 5036 y Fe(keytype)857 b(interpretation)382 5149 y(-------)475 b(-------------------------)o(----)o(---)o(----)o(----)o(---)o(----)o (--)525 5262 y(-2)572 b(Rename)46 b(the)h(keyword)f(with)h(name)f(=)i (the)f(first)f(8)h(characters)e(of)j(CARD)1193 5375 y(to)f(the)g(new)g (name)g(given)f(in)h(characters)e(41)j(-)f(48)g(of)g(CARD.)525 5601 y(-1)572 b(delete)46 b(the)h(keyword)f(with)h(this)f(name)h(from)g (the)f(FITS)h(header.)p eop %%Page: 61 69 61 68 bop 0 299 a Fh(5.8.)72 b(UTILITY)30 b(R)m(OUTINES)2693 b Fj(61)573 555 y Fe(0)572 b(append)46 b(the)h(CARD)g(string)f(to)h (the)g(FITS)g(header)f(if)h(the)1193 668 y(keyword)f(does)h(not)g (already)e(exist,)h(otherwise)g(update)1193 781 y(the)h(keyword)f (value)g(and/or)g(comment)g(field)h(if)g(is)g(already)f(exists.)573 1007 y(1)572 b(This)47 b(is)g(a)g(HISTORY)f(or)h(COMMENT)f(keyword;)g (append)g(it)h(to)g(the)g(header)573 1233 y(2)572 b(END)47 b(record;)f(do)h(not)g(explicitly)e(write)h(it)i(to)f(the)g(FITS)f (file.)0 1458 y Fj(EXAMPLES:)30 b(The)g(follo)m(wing)f(lines)f (illustrate)h(v)-5 b(alid)29 b(input)f(template)j(strings:)286 1682 y Fe(INTVAL)46 b(7)i(/)f(This)g(is)g(an)g(integer)f(keyword)286 1795 y(RVAL)524 b(34.6)142 b(/)239 b(This)46 b(is)i(a)f(floating)f (point)g(keyword)286 1908 y(EVAL=-12.45E-03)92 b(/)47 b(This)g(is)g(a)g(floating)f(point)g(keyword)g(in)h(exponential)e (notation)286 2021 y(lval)i(F)g(/)h(This)f(is)g(a)g(boolean)f(keyword) 859 2134 y(This)h(is)g(a)g(comment)f(keyword)g(with)h(a)g(blank)f (keyword)g(name)286 2247 y(SVAL1)h(=)g('Hello)f(world')142 b(/)95 b(this)47 b(is)g(a)g(string)f(keyword)286 2360 y(SVAL2)94 b('123.5')g(this)47 b(is)g(also)f(a)i(string)e(keyword)286 2473 y(sval3)94 b(123+)h(/)g(this)47 b(is)g(also)f(a)i(string)e (keyword)g(with)g(the)h(value)g('123+)189 b(')286 2586 y(#)48 b(the)f(following)e(template)h(line)g(deletes)g(the)h(DATE)g (keyword)286 2699 y(-)h(DATE)286 2812 y(#)g(the)f(following)e(template) h(line)g(modifies)g(the)h(NAME)f(keyword)g(to)h(OBJECT)286 2924 y(-)h(NAME)e(OBJECT)0 3149 y Fi(18)g Fj(P)m(arse)35 b(the)g(input)e(string)h(con)m(taining)g(a)h(list)f(of)h(ro)m(ws)f(or)h (ro)m(w)g(ranges,)h(and)e(return)g(in)m(teger)h(arra)m(ys)g(con-)227 3262 y(taining)25 b(the)h(\014rst)f(and)g(last)h(ro)m(w)g(in)e(eac)m(h) j(range.)40 b(F)-8 b(or)26 b(example,)h(if)d(ro)m(wlist)h(=)g("3-5,)k (6,)e(8-9")h(then)d(it)h(will)227 3375 y(return)34 b(n)m(umranges)h(=)g (3,)h(rangemin)e(=)h(3,)i(6,)g(8)e(and)g(rangemax)g(=)g(5,)i(6,)g(9.)55 b(A)m(t)36 b(most,)h('maxranges')227 3488 y(n)m(um)m(b)s(er)31 b(of)h(ranges)f(will)e(b)s(e)j(returned.)43 b('maxro)m(ws')32 b(is)f(the)h(maxim)m(um)f(n)m(um)m(b)s(er)f(of)i(ro)m(ws)g(in)e(the)i (table;)227 3601 y(an)m(y)e(ro)m(ws)f(or)g(ranges)g(larger)g(than)g (this)f(will)e(b)s(e)j(ignored.)39 b(The)29 b(ro)m(ws)g(m)m(ust)g(b)s (e)f(sp)s(eci\014ed)g(in)f(increasing)227 3714 y(order,)33 b(and)f(the)g(ranges)h(m)m(ust)f(not)g(o)m(v)m(erlap.)47 b(A)33 b(min)m(us)d(sign)i(ma)m(y)h(b)s(e)e(use)h(to)h(sp)s(ecify)e (all)g(the)i(ro)m(ws)f(to)227 3827 y(the)h(upp)s(er)d(or)j(lo)m(w)m(er) g(b)s(ound,)e(so)i("50-")h(means)e(all)g(the)h(ro)m(ws)f(from)g(50)h (to)h(the)e(end)g(of)h(the)f(table,)i(and)227 3940 y("-")e(means)e(all) f(the)i(ro)m(ws)f(in)f(the)i(table,)f(from)g(1)h(-)g(maxro)m(ws.)191 4165 y Fe(int)47 b(fits_parse_range)c(/)48 b(ffrwrg\(char)c(*rowlist,)i (long)g(maxrows,)g(int)h(maxranges,)e(>)334 4278 y(int)i(*numranges,)e (long)h(*rangemin,)f(long)i(*rangemax,)e(int)i(*status\))0 4503 y Fi(19)f Fj(Chec)m(k)37 b(that)g(the)g(Header)g(\014ll)e(b)m (ytes)i(\(if)f(an)m(y\))h(are)g(all)f(blank.)58 b(These)36 b(are)h(the)g(b)m(ytes)g(that)g(ma)m(y)h(follo)m(w)227 4615 y(END)e(k)m(eyw)m(ord)g(and)f(b)s(efore)g(the)h(b)s(eginning)d(of) j(data)g(unit,)f(or)h(the)g(end)f(of)g(the)h(HDU)g(if)f(there)g(is)g (no)227 4728 y(data)c(unit.)191 4953 y Fe(int)47 b(ffchfl\(fitsfile)c (*fptr,)k(>)g(int)g(*status\))0 5178 y Fi(20)f Fj(Chec)m(k)30 b(that)g(the)f(Data)i(\014ll)c(b)m(ytes)j(\(if)f(an)m(y\))h(are)g(all)e (zero)i(\(for)f(IMA)m(GE)i(or)e(BINAR)-8 b(Y)30 b(T)-8 b(able)29 b(HDU\))i(or)e(all)227 5291 y(blanks)f(\(for)h(ASCI)s(I)f (table)h(HDU\).)h(These)f(\014le)f(b)m(ytes)i(ma)m(y)f(b)s(e)g(lo)s (cated)g(after)h(the)f(last)g(v)-5 b(alid)27 b(data)j(b)m(yte)227 5404 y(in)f(the)i(HDU)g(and)f(b)s(efore)g(the)g(ph)m(ysical)f(end)h(of) h(the)f(HDU.)191 5629 y Fe(int)47 b(ffcdfl\(fitsfile)c(*fptr,)k(>)g (int)g(*status\))p eop %%Page: 62 70 62 69 bop 0 299 a Fj(62)1379 b Fh(CHAPTER)30 b(5.)71 b(BASIC)30 b(CFITSIO)f(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)p eop %%Page: 63 71 63 70 bop 0 1225 a Fg(Chapter)65 b(6)0 1687 y Fm(The)77 b(CFITSIO)f(Iterator)i(F)-19 b(unction)0 2180 y Fj(The)41 b(\014ts)p 325 2180 28 4 v 33 w(iterate)p 615 2180 V 33 w(data)i(function)d(in)h(CFITSIO)f(pro)m(vides)h(a)h(unique)d(metho) s(d)j(of)g(executing)g(an)f(arbitrary)0 2293 y(user-supplied)33 b(`w)m(ork')k(function)e(that)i(op)s(erates)g(on)g(ro)m(ws)f(of)h(data) g(in)e(FITS)h(tables)g(or)g(on)h(pixels)d(in)i(FITS)0 2406 y(images.)i(Rather)24 b(than)e(explicitly)f(reading)h(and)h (writing)e(the)i(FITS)g(images)g(or)g(columns)f(of)h(data,)i(one)f (instead)0 2518 y(calls)34 b(the)i(CFITSIO)d(iterator)j(routine,)g (passing)e(to)i(it)f(the)g(name)g(of)h(the)f(user's)g(w)m(ork)g (function)f(that)i(is)e(to)0 2631 y(b)s(e)c(executed)h(along)f(with)f (a)i(list)e(of)h(all)f(the)i(table)f(columns)f(or)h(image)g(arra)m(ys)h (that)g(are)f(to)h(b)s(e)f(passed)g(to)h(the)0 2744 y(w)m(ork)37 b(function.)60 b(The)37 b(CFITSIO)e(iterator)j(function)e(then)h(do)s (es)g(all)f(the)h(w)m(ork)g(of)h(allo)s(cating)e(memory)h(for)0 2857 y(the)28 b(arra)m(ys,)h(reading)e(the)h(input)d(data)k(from)e(the) h(FITS)f(\014le,)g(passing)g(them)h(to)g(the)g(w)m(ork)g(function,)f (and)g(then)0 2970 y(writing)34 b(an)m(y)j(output)f(data)h(bac)m(k)h (to)f(the)f(FITS)g(\014le)f(after)i(the)g(w)m(ork)g(function)e(exits.) 58 b(Because)38 b(it)e(is)g(often)0 3083 y(more)h(e\016cien)m(t)h(to)g (pro)s(cess)f(only)f(a)i(subset)f(of)g(the)g(total)h(table)g(ro)m(ws)f (at)h(one)f(time,)i(the)f(iterator)f(function)0 3196 y(can)f(determine)f(the)i(optim)m(um)e(amoun)m(t)h(of)g(data)h(to)g (pass)e(in)g(eac)m(h)i(iteration)f(and)f(rep)s(eatly)g(call)h(the)g(w)m (ork)0 3309 y(function)29 b(un)m(til)g(the)h(en)m(tire)h(table)f(b)s (een)f(pro)s(cessed.)0 3469 y(F)-8 b(or)37 b(man)m(y)f(applications)e (this)g(single)h(CFITSIO)f(iterator)j(function)d(can)i(e\013ectiv)m (ely)h(replace)f(all)f(the)h(other)0 3582 y(CFITSIO)g(routines)h(for)g (reading)g(or)g(writing)f(data)i(in)e(FITS)h(images)h(or)f(tables.)63 b(Using)36 b(the)i(iterator)g(has)0 3695 y(sev)m(eral)31 b(imp)s(ortan)m(t)e(adv)-5 b(an)m(tages)32 b(o)m(v)m(er)g(the)f (traditional)d(metho)s(d)i(of)h(reading)e(and)h(writing)e(FITS)i(data)h (\014les:)136 3961 y Fc(\017)46 b Fj(It)33 b(cleanly)f(separates)i(the) f(data)h(I/O)f(from)f(the)h(routine)f(that)i(op)s(erates)f(on)g(the)g (data.)49 b(This)31 b(leads)h(to)227 4074 y(a)f(more)g(mo)s(dular)d (and)i(`ob)5 b(ject)31 b(orien)m(ted')g(programming)e(st)m(yle.)136 4268 y Fc(\017)46 b Fj(It)27 b(simpli\014es)c(the)k(application)e (program)i(b)m(y)f(eliminating)e(the)j(need)g(to)g(allo)s(cate)g (memory)g(for)f(the)h(data)227 4381 y(arra)m(ys)e(and)f(eliminates)f (most)h(of)h(the)f(calls)g(to)h(the)g(CFITSIO)d(routines)i(that)h (explicitly)d(read)i(and)g(write)227 4494 y(the)31 b(data.)136 4689 y Fc(\017)46 b Fj(It)32 b(ensures)e(that)i(the)g(data)g(are)g(pro) s(cessed)f(as)h(e\016cien)m(tly)f(as)g(p)s(ossible.)42 b(This)30 b(is)g(esp)s(ecially)g(imp)s(ortan)m(t)227 4801 y(when)44 b(pro)s(cessing)f(tabular)h(data)i(since)e(the)h (iterator)g(function)e(will)f(calculate)j(the)g(most)g(e\016cien)m(t) 227 4914 y(n)m(um)m(b)s(er)36 b(of)i(ro)m(ws)g(in)e(the)i(table)f(to)h (b)s(e)f(passed)g(at)i(one)e(time)h(to)g(the)g(user's)e(w)m(ork)i (function)e(on)i(eac)m(h)227 5027 y(iteration.)136 5222 y Fc(\017)46 b Fj(Mak)m(es)39 b(it)d(p)s(ossible)f(for)i(larger)g(pro)5 b(jects)37 b(to)h(dev)m(elop)f(a)h(library)c(of)k(w)m(ork)f(functions)f (that)h(all)f(ha)m(v)m(e)j(a)227 5335 y(uniform)28 b(calling)h (sequence)i(and)f(are)h(all)e(indep)s(enden)m(t)f(of)j(the)f(details)g (of)g(the)h(FITS)e(\014le)h(format.)0 5601 y(There)g(are)h(basically)e (2)j(steps)e(in)g(using)f(the)i(CFITSIO)e(iterator)i(function.)41 b(The)30 b(\014rst)g(step)h(is)f(to)h(design)f(the)0 5714 y(w)m(ork)c(function)e(itself)g(whic)m(h)g(m)m(ust)i(ha)m(v)m(e)g (a)g(prescrib)s(ed)d(set)j(of)g(input)e(parameters.)39 b(One)25 b(of)h(these)g(parameters)1905 5942 y(63)p eop %%Page: 64 72 64 71 bop 0 299 a Fj(64)1455 b Fh(CHAPTER)30 b(6.)112 b(THE)30 b(CFITSIO)e(ITERA)-8 b(TOR)30 b(FUNCTION)0 555 y Fj(is)e(a)h(structure)g(con)m(taining)g(p)s(oin)m(ters)e(to)j(the)f (arra)m(ys)h(of)f(data;)h(the)f(w)m(ork)h(function)d(can)j(p)s(erform)d (an)m(y)i(desired)0 668 y(op)s(erations)j(on)i(these)f(arra)m(ys)h(and) e(do)s(es)h(not)g(need)g(to)h(w)m(orry)f(ab)s(out)g(ho)m(w)g(the)h (input)d(data)j(w)m(ere)f(read)g(from)0 781 y(the)e(\014le)e(or)h(ho)m (w)h(the)f(output)g(data)h(get)h(written)d(bac)m(k)i(to)h(the)e (\014le.)0 941 y(The)24 b(second)h(step)g(is)e(to)j(design)d(the)i (driv)m(er)f(routine)f(that)j(op)s(ens)e(all)f(the)i(necessary)g(FITS)f (\014les)g(and)g(initializes)0 1054 y(the)41 b(input)f(parameters)h(to) h(the)g(iterator)f(function.)72 b(The)41 b(driv)m(er)f(program)h(calls) f(the)i(CFITSIO)e(iterator)0 1167 y(function)29 b(whic)m(h)g(then)h (reads)g(the)h(data)g(and)f(passes)g(it)g(to)h(the)g(user's)e(w)m(ork)i (function.)0 1327 y(The)20 b(follo)m(wing)f(2)i(sections)f(describ)s(e) f(these)i(steps)g(in)e(more)h(detail.)37 b(There)20 b(are)h(also)f(sev) m(eral)h(example)f(programs)0 1440 y(included)28 b(with)h(the)h (CFITSIO)f(distribution)e(whic)m(h)i(illustrate)g(ho)m(w)h(to)h(use)f (the)h(iterator)f(function.)0 1789 y Ff(6.1)135 b(The)45 b(Iterator)h(W)-11 b(ork)45 b(F)-11 b(unction)0 2043 y Fj(The)42 b(user-supplied)d(iterator)k(w)m(ork)g(function)e(m)m(ust)h (ha)m(v)m(e)i(the)f(follo)m(wing)e(set)i(of)g(input)d(parameters)j (\(the)0 2156 y(function)29 b(can)i(b)s(e)e(giv)m(en)i(an)m(y)g (desired)d(name\):)95 2429 y Fe(int)47 b(user_fn\()f(long)h(totaln,)e (long)i(offset,)f(long)g(firstn,)g(long)h(nvalues,)716 2542 y(int)g(narrays,)e(iteratorCol)g(*data,)94 b(void)47 b(*userPointer)d(\))136 2815 y Fc(\017)i Fj(totaln)23 b({)g(the)f(total)i(n)m(um)m(b)s(er)d(of)h(table)h(ro)m(ws)f(or)g (image)h(pixels)e(that)i(will)c(b)s(e)j(passed)g(to)h(the)g(w)m(ork)f (function)227 2928 y(during)28 b(1)j(or)g(more)f(iterations.)136 3129 y Fc(\017)46 b Fj(o\013set)d({)f(the)h(o\013set)f(applied)e(to)j (the)f(\014rst)f(table)h(ro)m(w)g(or)g(image)g(pixel)e(to)j(b)s(e)e (passed)g(to)i(the)f(w)m(ork)227 3241 y(function.)54 b(In)34 b(other)i(w)m(ords,)g(this)e(is)g(the)h(n)m(um)m(b)s(er)f(of)h (ro)m(ws)h(or)f(pixels)e(that)j(are)f(skipp)s(ed)e(o)m(v)m(er)j(b)s (efore)227 3354 y(starting)29 b(the)h(iterations.)40 b(If)28 b(o\013set)j(=)e(0,)h(then)f(all)f(the)h(table)h(ro)m(ws)f(or)g (image)h(pixels)d(will)g(b)s(e)h(passed)h(to)227 3467 y(the)i(w)m(ork)f(function.)136 3668 y Fc(\017)46 b Fj(\014rstn)26 b({)i(the)f(n)m(um)m(b)s(er)f(of)i(the)f(\014rst)g(table)g(ro)m(w)g(or) g(image)h(pixel)d(\(starting)j(with)e(1\))i(that)f(is)g(b)s(eing)e (passed)227 3781 y(in)k(this)h(particular)e(call)i(to)h(the)g(w)m(ork)f (function.)136 3982 y Fc(\017)46 b Fj(n)m(v)-5 b(alues)34 b({)h(the)f(n)m(um)m(b)s(er)g(of)g(table)g(ro)m(ws)h(or)f(image)h (pixels)d(that)j(are)g(b)s(eing)e(passed)h(in)f(this)h(particular)227 4095 y(call)g(to)i(the)f(w)m(ork)f(function.)53 b(n)m(v)-5 b(alues)34 b(will)e(alw)m(a)m(ys)j(b)s(e)f(less)g(than)g(or)h(equal)f (to)i(totaln)f(and)f(will)e(ha)m(v)m(e)227 4208 y(the)i(same)f(v)-5 b(alue)33 b(on)g(eac)m(h)h(iteration,)g(except)g(p)s(ossibly)d(on)i (the)g(last)g(call)g(whic)m(h)f(ma)m(y)h(ha)m(v)m(e)i(a)e(smaller)227 4321 y(v)-5 b(alue.)136 4522 y Fc(\017)46 b Fj(narra)m(ys)31 b({)g(the)g(n)m(um)m(b)s(er)f(of)h(arra)m(ys)g(of)g(data)h(that)f(are)g (b)s(eing)f(passed)g(to)i(the)f(w)m(ork)g(function.)41 b(There)30 b(is)227 4635 y(one)h(arra)m(y)g(for)f(eac)m(h)i(image)e(or) g(table)h(column.)136 4835 y Fc(\017)46 b Fj(*data)31 b({)e(arra)m(y)h(of)f(structures,)g(one)h(for)f(eac)m(h)h(column)e(or)h (image.)41 b(Eac)m(h)29 b(structure)g(con)m(tains)g(a)h(p)s(oin)m(ter) 227 4948 y(to)h(the)g(arra)m(y)g(of)f(data)h(as)g(w)m(ell)e(as)i(other) g(descriptiv)m(e)e(parameters)i(ab)s(out)f(that)h(arra)m(y)-8 b(.)136 5149 y Fc(\017)46 b Fj(*userP)m(oin)m(ter)25 b({)h(a)f(user)f(supplied)e(p)s(oin)m(ter)i(that)i(can)f(b)s(e)f(used)h (to)g(pass)g(ancillary)e(information)g(from)i(the)227 5262 y(driv)m(er)g(function)g(to)h(the)g(w)m(ork)g(function.)38 b(This)24 b(p)s(oin)m(ter)h(is)g(passed)h(to)g(the)h(CFITSIO)d (iterator)i(function)227 5375 y(whic)m(h)36 b(then)g(passes)g(it)g(on)h (to)g(the)f(w)m(ork)h(function)e(without)h(an)m(y)h(mo)s(di\014cation.) 57 b(It)37 b(ma)m(y)g(p)s(oin)m(t)e(to)j(a)227 5488 y(single)27 b(n)m(um)m(b)s(er,)h(to)h(an)f(arra)m(y)h(of)g(v)-5 b(alues,)28 b(to)h(a)g(structure)f(con)m(taining)g(an)g(arbitrary)f(set)i(of)g (parameters)227 5601 y(of)e(di\013eren)m(t)g(t)m(yp)s(es,)h(or)f(it)g (ma)m(y)g(b)s(e)g(a)g(n)m(ull)e(p)s(oin)m(ter)h(if)g(it)h(is)f(not)h (needed.)40 b(The)26 b(w)m(ork)h(function)f(m)m(ust)h(cast)227 5714 y(this)j(p)s(oin)m(ter)f(to)i(the)g(appropriate)e(data)i(t)m(yp)s (e)g(b)s(efore)f(using)e(it)i(it.)p eop %%Page: 65 73 65 72 bop 0 299 a Fh(6.1.)72 b(THE)30 b(ITERA)-8 b(TOR)30 b(W)m(ORK)g(FUNCTION)2021 b Fj(65)0 555 y(The)23 b(totaln,)j(o\013set,) h(narra)m(ys,)e(data,)h(and)d(userP)m(oin)m(ter)h(parameters)g(are)g (guaran)m(teed)h(to)g(ha)m(v)m(e)g(the)f(same)g(v)-5 b(alue)0 668 y(on)35 b(eac)m(h)i(iteration.)55 b(Only)33 b(\014rstn,)j(n)m(v)-5 b(alues,)36 b(and)e(the)i(arra)m(ys)f(of)h(data) g(p)s(oin)m(ted)e(to)i(b)m(y)f(the)h(data)g(structures)0 781 y(ma)m(y)31 b(c)m(hange)g(on)g(eac)m(h)g(iterativ)m(e)g(call)f(to)h (the)f(w)m(ork)h(function.)0 941 y(Note)43 b(that)g(the)f(iterator)g (treats)h(an)f(image)g(as)g(a)g(long)g(1-D)h(arra)m(y)f(of)h(pixels)d (regardless)h(of)h(it's)g(in)m(trinsic)0 1054 y(dimensionalit)m(y)-8 b(.)48 b(The)33 b(total)i(n)m(um)m(b)s(er)d(of)i(pixels)e(is)h(just)g (the)h(pro)s(duct)e(of)i(the)g(size)g(of)f(eac)m(h)i(dimension,)e(and)0 1167 y(the)g(order)g(of)g(the)g(pixels)e(is)h(the)h(same)g(as)g(the)h (order)e(that)h(they)h(are)f(stored)g(in)f(the)h(FITS)f(\014le.)47 b(If)33 b(the)g(w)m(ork)0 1280 y(function)26 b(needs)h(to)h(kno)m(w)f (the)h(n)m(um)m(b)s(er)e(and)h(size)g(of)h(the)f(image)h(dimensions)c (then)j(these)h(parameters)g(can)g(b)s(e)0 1393 y(passed)i(via)g(the)g (userP)m(oin)m(ter)h(structure.)0 1553 y(The)f(iteratorCol)g(structure) g(is)f(curren)m(tly)h(de\014ned)f(as)h(follo)m(ws:)0 1780 y Fe(typedef)46 b(struct)94 b(/*)47 b(structure)e(for)i(the)g (iterator)e(function)h(column)g(information)f(*/)0 1893 y({)143 2005 y(/*)i(structure)f(elements)f(required)h(as)h(input)f(to)h (fits_iterate_data:)c(*/)95 2231 y(fitsfile)j(*fptr;)332 b(/*)48 b(pointer)d(to)j(the)f(HDU)f(containing)f(the)i(column)f(or)i (image)e(*/)95 2344 y(int)286 b(colnum;)e(/*)48 b(column)e(number)g(in) h(the)g(table;)f(ignored)g(for)h(images)189 b(*/)95 2457 y(char)238 b(colname[70];)44 b(/*)k(name)e(\(TTYPEn\))g(of)h(the)g (column;)f(null)g(for)h(images)285 b(*/)95 2570 y(int)h(datatype;)188 b(/*)48 b(output)e(data)g(type)h(\(converted)e(if)i(necessary\))e(*/)95 2683 y(int)286 b(iotype;)e(/*)48 b(type:)e(InputCol,)f(InputOutputCol,) f(or)j(OutputCol)e(*/)95 2909 y(/*)j(output)e(structure)f(elements)h (that)g(may)h(be)g(useful)f(for)h(the)g(work)g(function:)e(*/)95 3135 y(void)238 b(*array;)189 b(/*)47 b(pointer)f(to)h(the)g(array)f (\(and)h(the)g(null)g(value\))f(*/)95 3247 y(long)238 b(repeat;)189 b(/*)47 b(binary)f(table)h(vector)f(repeat)g(value;)g (set)238 b(*/)1050 3360 y(/*)g(equal)46 b(to)i(1)f(for)g(images)810 b(*/)95 3473 y(long)238 b(tlmin;)f(/*)47 b(legal)g(minimum)e(data)i (value,)f(if)h(any)477 b(*/)95 3586 y(long)238 b(tlmax;)f(/*)47 b(legal)g(maximum)e(data)i(value,)f(if)h(any)477 b(*/)95 3699 y(char)238 b(unit[70];)93 b(/*)47 b(physical)f(unit)g(string)g (\(BUNIT)h(or)g(TUNITn\))189 b(*/)95 3812 y(char)238 b(tdisp[70];)45 b(/*)i(suggested)e(display)h(format;)g(null)h(if)g (none)190 b(*/)0 4038 y(})47 b(iteratorCol;)0 4264 y Fj(Instead)34 b(of)g(directly)e(reading)h(or)h(writing)e(the)h(elemen)m (ts)i(in)d(this)h(structure,)h(it)g(is)e(recommended)i(that)g(pro-)0 4377 y(grammers)c(use)g(the)h(access)h(functions)c(that)j(are)g(pro)m (vided)e(for)h(this)g(purp)s(ose.)0 4538 y(The)25 b(\014rst)g(\014v)m (e)h(elemen)m(ts)g(in)f(this)f(structure)i(m)m(ust)f(b)s(e)g(initially) e(de\014ned)h(b)m(y)i(the)g(driv)m(er)e(routine)h(b)s(efore)g(calling)0 4650 y(the)f(iterator)g(routine.)37 b(The)23 b(CFITSIO)f(iterator)i (routine)f(uses)g(this)f(information)g(to)i(determine)f(what)g(column)0 4763 y(or)32 b(arra)m(y)h(to)h(pass)e(to)h(the)g(w)m(ork)f(function,)g (and)g(whether)g(the)g(arra)m(y)h(is)f(to)h(b)s(e)f(input)f(to)i(the)f (w)m(ork)h(function,)0 4876 y(output)g(from)g(the)h(w)m(ork)f (function,)g(or)h(b)s(oth.)49 b(The)33 b(CFITSIO)f(iterator)h(function) f(\014lls)g(in)g(the)h(v)-5 b(alues)33 b(of)h(the)0 4989 y(remaining)28 b(structure)i(elemen)m(ts)h(b)s(efore)f(passing)f(it)h (to)h(the)g(w)m(ork)f(function.)0 5149 y(The)d(arra)m(y)g(structure)g (elemen)m(t)h(is)e(a)h(p)s(oin)m(ter)f(to)i(the)g(actual)f(data)h(arra) m(y)g(and)e(it)h(m)m(ust)g(b)s(e)f(cast)j(to)e(the)h(correct)0 5262 y(data)k(t)m(yp)s(e)f(b)s(efore)f(it)h(is)f(used.)41 b(The)31 b(`rep)s(eat')g(structure)g(elemen)m(t)g(giv)m(e)g(the)h(n)m (um)m(b)s(er)d(of)i(data)h(v)-5 b(alues)30 b(in)g(eac)m(h)0 5375 y(ro)m(w)g(of)g(the)g(table,)h(so)f(that)h(the)f(total)h(n)m(um)m (b)s(er)d(of)i(data)h(v)-5 b(alues)29 b(in)g(the)h(arra)m(y)h(is)e(giv) m(en)h(b)m(y)g(rep)s(eat)g(*)g(n)m(v)-5 b(alues.)0 5488 y(In)36 b(the)g(case)i(of)e(image)h(arra)m(ys)g(and)e(ASCI)s(I)g (tables,)j(rep)s(eat)f(will)d(alw)m(a)m(ys)i(b)s(e)g(equal)g(to)h(1.)59 b(When)37 b(the)f(data)0 5601 y(t)m(yp)s(e)k(is)e(a)i(c)m(haracter)h (string,)g(the)f(arra)m(y)g(p)s(oin)m(ter)e(is)h(actually)g(a)h(p)s (oin)m(ter)e(to)j(an)e(arra)m(y)h(of)g(string)e(p)s(oin)m(ters)0 5714 y(\(i.e.,)30 b(c)m(har)f(**arra)m(y\).)42 b(The)29 b(other)g(output)g(structure)f(elemen)m(ts)i(are)f(pro)m(vided)f(for)g (con)m(v)m(enience)j(in)c(case)j(that)p eop %%Page: 66 74 66 73 bop 0 299 a Fj(66)1455 b Fh(CHAPTER)30 b(6.)112 b(THE)30 b(CFITSIO)e(ITERA)-8 b(TOR)30 b(FUNCTION)0 555 y Fj(information)k(is)h(needed)g(within)e(the)j(w)m(ork)g(function.)55 b(An)m(y)35 b(other)h(information)e(ma)m(y)i(b)s(e)f(passed)h(from)f (the)0 668 y(driv)m(er)29 b(routine)h(to)h(the)f(w)m(ork)h(function)e (via)h(the)g(userP)m(oin)m(ter)g(parameter.)0 828 y(Up)s(on)h (completion,)h(the)g(w)m(ork)h(routine)e(m)m(ust)h(return)f(an)h(in)m (teger)g(status)g(v)-5 b(alue,)33 b(with)d(0)j(indicating)d(success)0 941 y(and)h(an)m(y)g(other)g(v)-5 b(alue)31 b(indicating)e(an)i(error)g (whic)m(h)f(will)e(cause)k(the)f(iterator)h(function)e(to)i (immediately)d(exit)0 1054 y(at)e(that)f(p)s(oin)m(t.)38 b(Return)25 b(status)i(v)-5 b(alues)25 b(in)f(the)i(range)h(1)f({)g (1000)i(should)23 b(b)s(e)j(a)m(v)m(oided)g(since)f(these)i(are)f (reserv)m(ed)0 1167 y(for)d(use)g(b)m(y)h(CFITSIO.)e(A)i(return)e (status)i(v)-5 b(alue)23 b(of)h(-1)g(ma)m(y)g(b)s(e)f(used)f(to)j (force)f(the)f(CFITSIO)f(iterator)i(function)0 1280 y(to)j(stop)g(at)g (that)h(p)s(oin)m(t)d(and)h(return)g(con)m(trol)h(to)g(the)g(driv)m(er) e(routine)h(after)h(writing)d(an)m(y)j(output)f(arra)m(ys)h(to)h(the)0 1393 y(FITS)e(\014le.)39 b(CFITSIO)26 b(do)s(es)g(not)i(considered)e (this)g(to)i(b)s(e)e(an)h(error)g(condition,)g(so)g(an)m(y)g(further)f (pro)s(cessing)g(b)m(y)0 1506 y(the)31 b(application)d(program)i(will)e (con)m(tin)m(ue)j(normally)-8 b(.)0 1837 y Ff(6.2)135 b(The)45 b(Iterator)h(Driv)l(er)g(F)-11 b(unction)0 2087 y Fj(The)33 b(iterator)g(driv)m(er)f(function)g(m)m(ust)i(op)s(en)e (the)i(necessary)f(FITS)g(\014les)f(and)h(p)s(osition)e(them)i(to)h (the)g(correct)0 2200 y(HDU.)23 b(It)f(m)m(ust)g(also)h(initialize)c (the)j(follo)m(wing)f(parameters)h(in)f(the)i(iteratorCol)f(structure)f (\(de\014ned)g(ab)s(o)m(v)m(e\))j(for)0 2313 y(eac)m(h)31 b(column)e(or)h(image)g(b)s(efore)f(calling)g(the)h(CFITSIO)e(iterator) i(function.)39 b(Sev)m(eral)30 b(`constructor')h(routines)0 2426 y(are)g(pro)m(vided)e(in)g(CFITSIO)g(for)h(this)f(purp)s(ose.)136 2670 y Fc(\017)46 b Fj(*fptr)30 b({)h(The)f(\014ts\014le)f(p)s(oin)m (ter)g(to)j(the)e(table)g(or)h(image.)136 2853 y Fc(\017)46 b Fj(coln)m(um)29 b({)g(the)h(n)m(um)m(b)s(er)e(of)h(the)h(column)e(in) g(the)h(table.)41 b(This)27 b(v)-5 b(alue)29 b(is)f(ignored)g(in)g(the) i(case)g(of)g(images.)227 2966 y(If)j(coln)m(um)g(equals)g(0,)h(then)g (the)f(column)f(name)i(will)c(b)s(e)j(used)g(to)h(iden)m(tify)e(the)h (column)g(to)h(b)s(e)e(passed)227 3079 y(to)f(the)g(w)m(ork)f (function.)136 3261 y Fc(\017)46 b Fj(colname)31 b({)f(the)g(name)h (\(TTYPEn)e(k)m(eyw)m(ord\))i(of)f(the)h(column.)39 b(This)28 b(is)i(only)f(required)f(if)h(coln)m(um)h(=)g(0)227 3374 y(and)g(is)f(ignored)h(for)g(images.)136 3556 y Fc(\017)46 b Fj(datat)m(yp)s(e)29 b({)g(The)e(desired)g(data)h(t)m(yp)s(e)g(of)h (the)f(arra)m(y)g(to)h(b)s(e)e(passed)h(to)h(the)f(w)m(ork)g(function.) 39 b(F)-8 b(or)28 b(n)m(umer-)227 3669 y(ical)f(data)h(the)f(data)h(t)m (yp)s(e)g(do)s(es)f(not)g(need)g(to)h(b)s(e)f(the)g(same)h(as)f(the)h (actual)f(data)h(t)m(yp)s(e)g(in)e(the)h(FITS)g(\014le,)227 3782 y(in)g(whic)m(h)h(case)h(CFITSIO)e(will)f(do)j(the)f(con)m(v)m (ersion.)41 b(Allo)m(w)m(ed)28 b(v)-5 b(alues)28 b(are:)40 b(TSTRING,)28 b(TLOGICAL,)227 3895 y(TBYTE,)37 b(TSBYTE,)f(TSHOR)-8 b(T,)36 b(TUSHOR)-8 b(T,)37 b(TINT,)f(TLONG,)h(TULONG,)f(TFLO)m(A)-8 b(T,)38 b(TDOU-)227 4008 y(BLE.)33 b(If)g(the)g(input)e(v)-5 b(alue)32 b(of)h(data)h(t)m(yp)s(e)f(equals)f(0,)j(then)d(the)h (existing)f(data)i(t)m(yp)s(e)f(of)g(the)g(column)f(or)227 4121 y(image)f(will)d(b)s(e)h(used)h(without)f(an)m(y)i(con)m(v)m (ersion.)136 4303 y Fc(\017)46 b Fj(iot)m(yp)s(e)36 b({)g(de\014nes)e (whether)h(the)h(data)g(arra)m(y)g(is)f(to)h(b)s(e)f(input)f(to)i(the)g (w)m(ork)f(function)g(\(i.e,)i(read)e(from)227 4416 y(the)42 b(FITS)e(\014le\),)j(or)e(output)g(from)g(the)g(w)m(ork)g(function)f (\(i.e.,)k(written)c(to)i(the)f(FITS)g(\014le\))f(or)h(b)s(oth.)227 4529 y(Allo)m(w)m(ed)28 b(v)-5 b(alues)28 b(are)g(InputCol,)f (OutputCol,)h(or)g(InputOutputCol.)37 b(V)-8 b(ariable-length)27 b(arra)m(y)i(columns)227 4642 y(are)h(supp)s(orted)e(as)i(InputCol)d (or)j(InputOutputCol)c(t)m(yp)s(es,)k(but)f(ma)m(y)h(not)g(b)s(e)e (used)h(for)g(an)h(OutputCol)227 4755 y(t)m(yp)s(e.)0 4999 y(After)h(the)f(driv)m(er)f(routine)g(has)h(initialized)e(all)h (these)h(parameters,)h(it)f(can)h(then)f(call)f(the)i(CFITSIO)e (iterator)0 5112 y(function:)95 5357 y Fe(int)47 b (fits_iterate_data\(int)42 b(narrays,)k(iteratorCol)f(*data,)h(long)g (offset,)286 5470 y(long)h(nPerLoop,)e(int)i(\(*workFn\)\()e(\),)i (void)g(*userPointer,)d(int)j(*status\);)136 5714 y Fc(\017)f Fj(narra)m(ys)31 b({)f(the)h(n)m(um)m(b)s(er)e(of)h(columns)f(or)i (images)f(that)h(are)g(to)g(b)s(e)f(passed)g(to)h(the)f(w)m(ork)h (function.)p eop %%Page: 67 75 67 74 bop 0 299 a Fh(6.3.)72 b(GUIDELINES)30 b(F)m(OR)h(USING)f(THE)g (ITERA)-8 b(TOR)30 b(FUNCTION)1200 b Fj(67)136 555 y Fc(\017)46 b Fj(*data)32 b({)f(p)s(oin)m(ter)e(to)i(arra)m(y)g(of)f (structures)g(con)m(taining)g(information)f(ab)s(out)h(eac)m(h)h (column)f(or)g(image.)136 736 y Fc(\017)46 b Fj(o\013set)31 b({)f(if)e(p)s(ositiv)m(e,)h(this)g(n)m(um)m(b)s(er)f(of)i(ro)m(ws)f (at)h(the)g(b)s(eginning)d(of)j(the)f(table)h(\(or)g(pixels)d(in)i(the) g(image\))227 849 y(will)f(b)s(e)i(skipp)s(ed)e(and)h(will)f(not)j(b)s (e)e(passed)h(to)h(the)g(w)m(ork)f(function.)136 1030 y Fc(\017)46 b Fj(nP)m(erLo)s(op)38 b(-)h(sp)s(eci\014es)d(the)j(n)m (um)m(b)s(er)e(of)h(table)g(ro)m(ws)h(\(or)f(n)m(um)m(b)s(er)f(of)i (image)f(pixels\))f(that)i(are)g(to)g(b)s(e)227 1143 y(passed)29 b(to)h(the)f(w)m(ork)h(function)d(on)i(eac)m(h)i (iteration.)40 b(If)28 b(nP)m(erLo)s(op)h(=)g(0)g(then)g(CFITSIO)f (will)f(calculate)227 1256 y(the)22 b(optim)m(um)f(n)m(um)m(b)s(er)f (for)h(greatest)j(e\016ciency)-8 b(.)38 b(If)21 b(nP)m(erLo)s(op)g(is)g (negativ)m(e,)k(then)c(all)g(the)h(ro)m(ws)f(or)h(pixels)227 1368 y(will)33 b(b)s(e)i(passed)g(at)h(one)g(time,)h(and)d(the)i(w)m (ork)g(function)e(will)f(only)h(b)s(e)h(called)g(once.)56 b(If)35 b(an)m(y)h(v)-5 b(ariable)227 1481 y(length)32 b(arra)m(ys)h(are)g(b)s(eing)e(pro)s(cessed,)i(then)g(the)f(nP)m(erLo)s (op)h(v)-5 b(alue)32 b(is)f(ignored,)i(and)f(the)h(iterator)g(will)227 1594 y(alw)m(a)m(ys)e(pro)s(cess)f(one)h(ro)m(w)f(of)h(the)f(table)h (at)g(a)g(time.)136 1775 y Fc(\017)46 b Fj(*w)m(orkFn)f(-)f(the)h(name) f(\(actually)g(the)h(address\))f(of)g(the)g(w)m(ork)h(function)e(that)i (is)e(to)i(b)s(e)f(called)f(b)m(y)227 1888 y(\014ts)p 354 1888 28 4 v 33 w(iterate)p 644 1888 V 33 w(data.)136 2069 y Fc(\017)j Fj(*userP)m(oin)m(ter)33 b(-)g(this)f(is)g(a)h(user)f (supplied)e(p)s(oin)m(ter)i(that)h(can)g(b)s(e)g(used)f(to)h(pass)g (ancillary)e(information)227 2182 y(from)i(the)g(driv)m(er)f(routine)g (to)i(the)f(w)m(ork)g(function.)47 b(It)33 b(ma)m(y)h(p)s(oin)m(t)e(to) i(a)f(single)f(n)m(um)m(b)s(er,)g(an)h(arra)m(y)-8 b(,)35 b(or)227 2295 y(to)c(a)g(structure)f(con)m(taining)g(an)g(arbitrary)f (set)i(of)g(parameters.)136 2476 y Fc(\017)46 b Fj(*status)30 b(-)f(The)f(CFITSIO)f(error)h(status.)41 b(Should)26 b(=)i(0)h(on)g(input;)e(a)i(non-zero)h(output)e(v)-5 b(alue)28 b(indicates)227 2588 y(an)j(error.)0 2828 y(When)f(\014ts)p 392 2828 V 32 w(iterate)p 681 2828 V 34 w(data)h(is)e(called)g(it)g (\014rst)h(allo)s(cates)g(memory)g(to)h(hold)d(all)h(the)h(requested)g (columns)f(of)h(data)0 2941 y(or)f(image)h(pixel)d(arra)m(ys.)41 b(It)29 b(then)g(reads)g(the)h(input)d(data)j(from)f(the)g(FITS)f (tables)h(or)h(images)f(in)m(to)g(the)h(arra)m(ys)0 3054 y(then)h(passes)h(the)g(structure)f(with)f(p)s(oin)m(ters)h(to)h(these) g(data)h(arra)m(ys)f(to)g(the)g(w)m(ork)g(function.)43 b(After)32 b(the)g(w)m(ork)0 3167 y(function)k(returns,)h(the)h (iterator)f(function)f(writes)g(an)m(y)h(output)g(columns)e(of)i(data)h (or)f(images)g(bac)m(k)h(to)g(the)0 3279 y(FITS)31 b(\014les.)45 b(It)32 b(then)g(rep)s(eats)g(this)f(pro)s(cess)h(for)f(an)m(y)i (remaining)d(sets)i(of)h(ro)m(ws)f(or)g(image)g(pixels)e(un)m(til)h(it) g(has)0 3392 y(pro)s(cessed)c(the)i(en)m(tire)f(table)f(or)h(image)h (or)f(un)m(til)e(the)i(w)m(ork)g(function)f(returns)g(a)h(non-zero)h (status)f(v)-5 b(alue.)39 b(The)0 3505 y(iterator)32 b(then)g(frees)g(the)h(memory)e(that)i(it)f(initially)c(allo)s(cated)k (and)g(returns)f(con)m(trol)h(to)h(the)f(driv)m(er)f(routine)0 3618 y(that)g(called)f(it.)0 3949 y Ff(6.3)135 b(Guidelines)46 b(for)f(Using)h(the)f(Iterator)h(F)-11 b(unction)0 4199 y Fj(The)34 b(totaln,)h(o\013set,)i(\014rstn,)d(and)f(n)m(v)-5 b(alues)34 b(parameters)g(that)h(are)f(passed)g(to)h(the)f(w)m(ork)g (function)f(are)i(useful)0 4312 y(for)f(determining)e(ho)m(w)i(m)m(uc)m (h)g(of)h(the)f(data)h(has)f(b)s(een)f(pro)s(cessed)h(and)f(ho)m(w)h(m) m(uc)m(h)g(remains)f(left)h(to)h(do.)52 b(On)0 4425 y(the)36 b(v)m(ery)h(\014rst)f(call)f(to)i(the)f(w)m(ork)h(function)e(\014rstn)g (will)e(b)s(e)j(equal)g(to)h(o\013set)g(+)f(1;)k(the)c(w)m(ork)g (function)f(ma)m(y)0 4538 y(need)c(to)g(p)s(erform)f(v)-5 b(arious)30 b(initialization)d(tasks)32 b(b)s(efore)e(starting)h(to)g (pro)s(cess)g(the)g(data.)43 b(Similarly)-8 b(,)28 b(\014rstn)h(+)0 4650 y(n)m(v)-5 b(alues)28 b(-)g(1)h(will)c(b)s(e)j(equal)f(to)i (totaln)g(on)f(the)g(last)g(iteration,)h(at)g(whic)m(h)e(p)s(oin)m(t)g (the)h(w)m(ork)h(function)d(ma)m(y)j(need)0 4763 y(to)k(p)s(erform)f (some)h(clean)g(up)e(op)s(erations)h(b)s(efore)h(exiting)f(for)g(the)h (last)g(time.)47 b(The)33 b(w)m(ork)f(function)g(can)h(also)0 4876 y(force)e(an)f(early)g(termination)f(of)i(the)g(iterations)e(b)m (y)i(returning)d(a)j(status)g(v)-5 b(alue)29 b(=)h(-1.)0 5036 y(The)f(narra)m(ys)g(and)g(iteratorCol.datat)m(yp)s(e)h(argumen)m (ts)g(allo)m(w)e(the)i(w)m(ork)f(function)f(to)i(double)e(c)m(hec)m(k)j (that)f(the)0 5149 y(n)m(um)m(b)s(er)k(of)i(input)e(arra)m(ys)i(and)f (their)f(data)j(t)m(yp)s(es)e(ha)m(v)m(e)i(the)f(exp)s(ected)g(v)-5 b(alues.)56 b(The)35 b(iteratorCol.fptr)g(and)0 5262 y(iteratorCol.coln)m(um)c(structure)g(elemen)m(ts)g(can)h(b)s(e)f(used) f(if)h(the)g(w)m(ork)h(function)e(needs)h(to)h(read)f(or)g(write)g(the) 0 5375 y(v)-5 b(alues)30 b(of)h(other)g(k)m(eyw)m(ords)g(in)f(the)h (FITS)f(\014le)g(asso)s(ciated)h(with)f(the)h(arra)m(y)-8 b(.)43 b(This)29 b(should)g(generally)h(only)g(b)s(e)0 5488 y(done)k(during)d(the)j(initialization)d(step)i(or)h(during)e(the) i(clean)f(up)g(step)h(after)g(the)g(last)g(set)g(of)g(data)g(has)g(b)s (een)0 5601 y(pro)s(cessed.)40 b(Extra)29 b(FITS)f(\014le)g(I/O)h (during)d(the)j(main)f(pro)s(cessing)g(lo)s(op)g(of)h(the)g(w)m(ork)g (function)f(can)h(seriously)0 5714 y(degrade)i(the)f(sp)s(eed)g(of)g (the)h(program.)p eop %%Page: 68 76 68 75 bop 0 299 a Fj(68)1455 b Fh(CHAPTER)30 b(6.)112 b(THE)30 b(CFITSIO)e(ITERA)-8 b(TOR)30 b(FUNCTION)0 555 y Fj(If)i(v)-5 b(ariable-length)32 b(arra)m(y)h(columns)f(are)h(b)s (eing)e(pro)s(cessed,)i(then)g(the)g(iterator)g(will)d(op)s(erate)k(on) f(one)g(ro)m(w)g(of)0 668 y(the)j(table)f(at)h(a)g(time.)56 b(In)34 b(this)h(case)h(the)g(the)f(rep)s(eat)h(elemen)m(t)g(in)e(the)i (in)m(teratorCol)f(structure)g(will)e(b)s(e)h(set)0 781 y(equal)c(to)h(the)g(n)m(um)m(b)s(er)e(of)h(elemen)m(ts)h(in)e(the)i (curren)m(t)f(ro)m(w)g(that)h(is)f(b)s(eing)f(pro)s(cessed.)0 941 y(One)k(imp)s(ortan)m(t)f(feature)i(of)f(the)h(iterator)g(is)e (that)i(the)f(\014rst)g(elemen)m(t)h(in)e(eac)m(h)i(arra)m(y)g(that)g (is)e(passed)h(to)h(the)0 1054 y(w)m(ork)f(function)f(giv)m(es)h(the)g (v)-5 b(alue)32 b(that)i(is)e(used)g(to)h(represen)m(t)g(n)m(ull)e(or)i (unde\014ned)d(v)-5 b(alues)33 b(in)e(the)i(arra)m(y)-8 b(.)49 b(The)0 1167 y(real)40 b(data)h(then)g(b)s(egins)e(with)g(the)h (second)h(elemen)m(t)g(of)g(the)f(arra)m(y)h(\(i.e.,)j(arra)m(y[1],)h (not)c(arra)m(y[0]\).)73 b(If)40 b(the)0 1280 y(\014rst)e(arra)m(y)h (elemen)m(t)g(is)f(equal)g(to)h(zero,)j(then)c(this)f(indicates)h(that) h(all)f(the)g(arra)m(y)h(elemen)m(ts)g(ha)m(v)m(e)h(de\014ned)0 1393 y(v)-5 b(alues)32 b(and)g(there)h(are)g(no)g(unde\014ned)d(v)-5 b(alues.)47 b(If)33 b(arra)m(y[0])h(is)e(not)h(equal)f(to)h(zero,)i (then)d(this)g(indicates)f(that)0 1506 y(some)j(of)g(the)g(data)h(v)-5 b(alues)33 b(are)h(unde\014ned)d(and)j(this)e(v)-5 b(alue)34 b(\(arra)m(y[0]\))i(is)c(used)h(to)i(represen)m(t)f(them.)51 b(In)33 b(the)0 1619 y(case)i(of)e(output)g(arra)m(ys)h(\(i.e.,)h (those)f(arra)m(ys)g(that)g(will)d(b)s(e)i(written)f(bac)m(k)i(to)h (the)e(FITS)g(\014le)f(b)m(y)i(the)g(iterator)0 1732 y(function)g(after)j(the)f(w)m(ork)f(function)g(exits\))h(the)g(w)m (ork)g(function)e(m)m(ust)i(set)g(the)g(\014rst)f(arra)m(y)h(elemen)m (t)g(to)h(the)0 1844 y(desired)f(n)m(ull)f(v)-5 b(alue)36 b(if)g(necessary)-8 b(,)40 b(otherwise)d(the)g(\014rst)g(elemen)m(t)g (should)e(b)s(e)i(set)g(to)h(zero)g(to)g(indicate)e(that)0 1957 y(there)30 b(are)h(no)e(n)m(ull)f(v)-5 b(alues)30 b(in)e(the)i(output)g(arra)m(y)-8 b(.)42 b(CFITSIO)28 b(de\014nes)h(2)h(v)-5 b(alues,)30 b(FLO)m(A)-8 b(TNULL)e(V)g(ALUE)31 b(and)0 2070 y(DOUBLENULL)-10 b(V)g(ALUE,)37 b(that)f(can)h(b)s(e)e (used)g(as)i(default)e(n)m(ull)f(v)-5 b(alues)35 b(for)h(\015oat)h(and) e(double)g(data)i(t)m(yp)s(es,)0 2183 y(resp)s(ectiv)m(ely)-8 b(.)58 b(In)35 b(the)i(case)g(of)f(c)m(haracter)i(string)d(data)i(t)m (yp)s(es,)h(a)e(n)m(ull)f(string)g(is)g(alw)m(a)m(ys)i(used)e(to)i (represen)m(t)0 2296 y(unde\014ned)28 b(strings.)0 2456 y(In)33 b(some)h(applications)d(it)i(ma)m(y)h(b)s(e)f(necessary)h(to)g (recursiv)m(ely)e(call)h(the)h(iterator)g(function.)49 b(An)33 b(example)g(of)0 2569 y(this)26 b(is)g(giv)m(en)h(b)m(y)g(one)h (of)f(the)h(example)e(programs)h(that)h(is)e(distributed)e(with)i (CFITSIO:)g(it)h(\014rst)f(calls)g(a)i(w)m(ork)0 2682 y(function)37 b(that)h(writes)g(out)g(a)g(2D)h(histogram)f(image.)64 b(That)38 b(w)m(ork)g(function)f(in)f(turn)h(calls)h(another)g(w)m(ork) 0 2795 y(function)28 b(that)i(reads)g(the)f(`X')i(and)e(`Y')h(columns)e (in)g(a)i(table)g(to)g(calculate)g(the)f(v)-5 b(alue)30 b(of)f(eac)m(h)i(2D)f(histogram)0 2908 y(image)h(pixel.)39 b(Graphically)-8 b(,)29 b(the)h(program)g(structure)g(can)h(b)s(e)f (describ)s(ed)e(as:)48 3153 y Fe(driver)46 b(-->)h(iterator)e(-->)i (work1_fn)f(-->)h(iterator)e(-->)i(work2_fn)0 3399 y Fj(Finally)-8 b(,)39 b(it)f(should)e(b)s(e)i(noted)g(that)h(the)g (table)f(columns)f(or)h(image)h(arra)m(ys)g(that)g(are)f(passed)g(to)h (the)g(w)m(ork)0 3512 y(function)34 b(do)i(not)g(all)e(ha)m(v)m(e)j(to) f(come)h(from)e(the)h(same)g(FITS)f(\014le)f(and)h(instead)g(ma)m(y)h (come)h(from)e(an)m(y)h(com-)0 3625 y(bination)31 b(of)i(sources)g(as)h (long)e(as)i(they)f(ha)m(v)m(e)h(the)f(same)h(length.)48 b(The)32 b(length)h(of)g(the)g(\014rst)f(table)h(column)f(or)0 3738 y(image)f(arra)m(y)g(is)e(used)g(b)m(y)i(the)f(iterator)h(if)e (they)i(do)f(not)h(all)e(ha)m(v)m(e)j(the)e(same)h(length.)0 4069 y Ff(6.4)135 b(Complete)47 b(List)e(of)g(Iterator)i(Routines)0 4319 y Fj(All)34 b(of)h(the)g(iterator)g(routines)f(are)h(listed)f(b)s (elo)m(w.)53 b(Most)36 b(of)f(these)h(routines)d(do)i(not)g(ha)m(v)m(e) i(a)e(corresp)s(onding)0 4432 y(short)30 b(function)f(name.)0 4678 y Fi(1)81 b Fj(Iterator)32 b(`constructor')h(functions)d(that)j (set)f(the)g(v)-5 b(alue)31 b(of)h(elemen)m(ts)g(in)f(the)h (iteratorCol)f(structure)g(that)227 4791 y(de\014ne)k(the)h(columns)e (or)i(arra)m(ys.)56 b(These)36 b(set)g(the)g(\014ts\014le)e(p)s(oin)m (ter,)i(column)e(name,)k(column)c(n)m(um)m(b)s(er,)227 4904 y(datat)m(yp)s(e,)28 b(and)e(iot)m(yp)s(e,)h(resp)s(ectiv)m(ely)-8 b(.)39 b(The)25 b(last)h(2)h(routines)e(allo)m(w)g(all)g(the)h (parameters)h(to)f(b)s(e)g(set)g(with)227 5017 y(one)31 b(function)e(call)h(\(one)h(supplies)c(the)k(column)e(name,)i(the)f (other)h(the)f(column)f(n)m(um)m(b)s(er\).)95 5262 y Fe(int)47 b(fits_iter_set_file\(iterato)o(rCo)o(l)42 b(*col,)k(fitsfile)g(*fptr\);)95 5488 y(int)h (fits_iter_set_colname\(iter)o(ato)o(rCol)41 b(*col,)46 b(char)h(*colname\);)95 5714 y(int)g(fits_iter_set_colnum\(itera)o(tor) o(Col)41 b(*col,)47 b(int)g(colnum\);)p eop %%Page: 69 77 69 76 bop 0 299 a Fh(6.4.)72 b(COMPLETE)29 b(LIST)g(OF)i(ITERA)-8 b(TOR)29 b(R)m(OUTINES)1638 b Fj(69)95 668 y Fe(int)47 b(fits_iter_set_datatype\(ite)o(rat)o(orCo)o(l)42 b(*col,)k(int)h (datatype\);)95 894 y(int)g(fits_iter_set_iotype\(itera)o(tor)o(Col)41 b(*col,)47 b(int)g(iotype\);)95 1120 y(int)g (fits_iter_set_by_name\(iter)o(ato)o(rCol)41 b(*col,)46 b(fitsfile)g(*fptr,)477 1233 y(char)h(*colname,)e(int)i(datatype,)93 b(int)47 b(iotype\);)95 1458 y(int)g(fits_iter_set_by_num\(itera)o(tor) o(Col)41 b(*col,)47 b(fitsfile)e(*fptr,)477 1571 y(int)i(colnum,)f(int) h(datatype,)93 b(int)47 b(iotype\);)0 1820 y Fi(2)81 b Fj(Iterator)38 b(`accessor')h(functions)d(that)h(return)g(the)g(v)-5 b(alue)37 b(of)g(the)g(elemen)m(t)h(in)e(the)h(iteratorCol)g(structure) 227 1933 y(that)31 b(describ)s(es)e(a)i(particular)d(data)j(column)f (or)g(arra)m(y)95 2181 y Fe(fitsfile)46 b(*)h (fits_iter_get_file\(iterato)o(rCol)41 b(*col\);)95 2407 y(char)47 b(*)h(fits_iter_get_colname\(i)o(ter)o(ator)o(Col)41 b(*col\);)95 2633 y(int)47 b(fits_iter_get_colnum\(itera)o(tor)o(Col)41 b(*col\);)95 2858 y(int)47 b(fits_iter_get_datatype\(ite)o(rat)o(orCo)o (l)42 b(*col\);)95 3084 y(int)47 b(fits_iter_get_iotype\(itera)o(tor)o (Col)41 b(*col\);)95 3310 y(void)47 b(*)h(fits_iter_get_array\(ite)o (rat)o(orCo)o(l)42 b(*col\);)95 3536 y(long)47 b (fits_iter_get_tlmin\(itera)o(tor)o(Col)41 b(*col\);)95 3762 y(long)47 b(fits_iter_get_tlmax\(itera)o(tor)o(Col)41 b(*col\);)95 3987 y(long)47 b(fits_iter_get_repeat\(iter)o(ato)o(rCol) 41 b(*col\);)95 4213 y(char)47 b(*)h(fits_iter_get_tunit\(ite)o(rat)o (orCo)o(l)42 b(*col\);)95 4439 y(char)47 b(*)h (fits_iter_get_tdisp\(ite)o(rat)o(orCo)o(l)42 b(*col\);)0 4687 y Fi(3)81 b Fj(The)29 b(CFITSIO)g(iterator)i(function)95 4936 y Fe(int)47 b(fits_iterate_data\(int)42 b(narrays,)94 b(iteratorCol)44 b(*data,)i(long)h(offset,)573 5049 y(long)f(nPerLoop,) 573 5161 y(int)h(\(*workFn\)\()e(long)h(totaln,)g(long)h(offset,)f (long)g(firstn,)1289 5274 y(long)g(nvalues,)g(int)h(narrays,)e (iteratorCol)g(*data,)1289 5387 y(void)h(*userPointer\),)573 5500 y(void)g(*userPointer,)573 5613 y(int)h(*status\);)p eop %%Page: 70 78 70 77 bop 0 299 a Fj(70)1455 b Fh(CHAPTER)30 b(6.)112 b(THE)30 b(CFITSIO)e(ITERA)-8 b(TOR)30 b(FUNCTION)p eop %%Page: 71 79 71 78 bop 0 1225 a Fg(Chapter)65 b(7)0 1687 y Fm(Celestial)76 b(Co)6 b(ordinate)78 b(System)f(Routines)0 2180 y Fj(The)36 b(FITS)g(comm)m(unit)m(y)g(has)g(adopted)h(a)g(set)g(of)g(k)m(eyw)m (ord)g(con)m(v)m(en)m(tions)g(that)g(de\014ne)f(the)h(transformations)0 2293 y(needed)30 b(to)i(con)m(v)m(ert)g(b)s(et)m(w)m(een)f(pixel)e(lo)s (cations)h(in)f(an)i(image)g(and)f(the)g(corresp)s(onding)f(celestial)h (co)s(ordinates)0 2406 y(on)25 b(the)h(sky)-8 b(,)27 b(or)e(more)g(generally)-8 b(,)27 b(that)f(de\014ne)e(w)m(orld)g(co)s (ordinates)i(that)f(are)h(to)g(b)s(e)f(asso)s(ciated)h(with)e(an)m(y)i (pixel)0 2518 y(lo)s(cation)34 b(in)f(an)i(n-dimensional)c(FITS)j(arra) m(y)-8 b(.)54 b(CFITSIO)33 b(is)g(distributed)f(with)h(a)i(couple)e(of) i(self-con)m(tained)0 2631 y(W)-8 b(orld)27 b(Co)s(ordinate)f(System)g (\(W)m(CS\))i(routines,)f(ho)m(w)m(ev)m(er,)i(these)f(routines)e(DO)h (NOT)f(supp)s(ort)f(all)h(the)h(latest)0 2744 y(W)m(CS)38 b(con)m(v)m(en)m(tions,)j(so)e(it)f(is)f(STR)m(ONGL)-8 b(Y)38 b(RECOMMENDED)h(that)f(soft)m(w)m(are)i(dev)m(elop)s(ers)d(use)h (a)h(more)0 2857 y(robust)30 b(external)g(W)m(CS)g(library)-8 b(.)39 b(Sev)m(eral)30 b(recommended)g(libraries)e(are:)95 3094 y Fe(WCSLIB)47 b(-)95 b(supported)45 b(by)i(Mark)g(Calabretta)95 3207 y(WCSTools)f(-)h(supported)f(by)h(Doug)g(Mink)95 3320 y(AST)g(library)f(-)i(developed)d(by)i(the)g(U.K.)g(Starlink)e (project)0 3556 y Fj(More)30 b(information)d(ab)s(out)i(the)g(W)m(CS)g (k)m(eyw)m(ord)h(con)m(v)m(en)m(tions)g(and)e(links)f(to)j(all)e(of)h (these)g(W)m(CS)g(libraries)e(can)0 3669 y(b)s(e)j(found)f(on)h(the)h (FITS)e(Supp)s(ort)g(O\016ce)h(w)m(eb)g(site)h(at)g(h)m (ttp://\014ts.gsfc.nasa.go)m(v)j(under)29 b(the)h(W)m(CS)h(link.)0 3829 y(The)i(functions)g(pro)m(vided)g(in)f(these)j(external)e(W)m(CS)h (libraries)e(will)f(need)j(access)h(to)g(the)f(W)m(CS)g(information)0 3942 y(con)m(tained)g(in)e(the)i(FITS)f(\014le)g(headers.)51 b(One)33 b(con)m(v)m(enien)m(t)i(w)m(a)m(y)g(to)f(pass)g(this)e (information)g(to)j(the)f(extermal)0 4055 y(library)29 b(is)g(to)j(use)f(the)g(\014ts)p 942 4055 28 4 v 32 w(hdr2str)f (routine)g(in)g(CFITSIO)f(\(de\014ned)h(b)s(elo)m(w\))g(to)i(cop)m(y)g (the)f(header)g(k)m(eyw)m(ords)0 4168 y(in)m(to)j(one)f(long)h(string,) f(and)g(then)g(pass)g(this)g(string)f(to)j(an)e(in)m(terface)h(routine) f(in)f(the)i(external)f(library)e(that)0 4281 y(will)i(extract)j(the)g (necessary)f(W)m(CS)g(information)f(\(e.g.,)k(see)e(the)f(astFitsChan)g (and)f(astPutCards)h(routines)0 4394 y(in)29 b(the)i(Starlink)d(AST)h (library\).)0 4631 y Fi(1)81 b Fj(Concatenate)38 b(the)f(header)f(k)m (eyw)m(ords)h(in)e(the)h(CHDU)h(in)m(to)g(a)g(single)e(long)h(string)f (of)i(c)m(haracters.)60 b(Eac)m(h)227 4744 y(80-c)m(haracter)28 b(\014xed-length)23 b(k)m(eyw)m(ord)i(record)g(is)f(app)s(ended)e(to)k (the)f(output)f(c)m(haracter)i(string,)f(in)e(order,)227 4856 y(with)h(no)g(in)m(terv)m(ening)g(separator)h(or)g(terminating)f (c)m(haracters.)40 b(The)24 b(last)h(header)f(record)h(is)e(terminated) 227 4969 y(with)32 b(a)h(NULL)f(c)m(haracter.)49 b(This)31 b(routine)h(allo)s(cates)h(memory)f(for)h(the)g(returned)e(c)m (haracter)j(arra)m(y)-8 b(,)35 b(so)227 5082 y(the)c(calling)e(program) h(m)m(ust)g(free)h(the)f(memory)g(when)g(\014nished.)227 5229 y(Selected)f(k)m(eyw)m(ords)f(ma)m(y)h(b)s(e)e(excluded)g(from)h (the)g(returned)f(c)m(haracter)j(string.)39 b(If)27 b(the)i(second)f (param-)227 5342 y(eter)h(\(no)s(commen)m(ts\))g(is)e(TR)m(UE)h (\(nonzero\))h(then)e(an)m(y)i(COMMENT,)f(HISTOR)-8 b(Y,)27 b(or)h(blank)f(k)m(eyw)m(ords)227 5455 y(in)i(the)i(header)f(will)e (not)i(b)s(e)g(copied)g(to)h(the)g(output)f(string.)227 5601 y(The)25 b('exclist')h(parameter)g(ma)m(y)g(b)s(e)f(used)g(to)h (supply)d(a)j(list)f(of)g(k)m(eyw)m(ords)h(that)h(are)f(to)g(b)s(e)f (excluded)f(from)227 5714 y(the)29 b(output)g(c)m(haracter)h(string.)40 b(Wild)27 b(card)i(c)m(haracters)h(\(*,)g(?,)f(and)g(#\))g(ma)m(y)g(b)s (e)f(used)g(in)g(the)h(excluded)1905 5942 y(71)p eop %%Page: 72 80 72 79 bop 0 299 a Fj(72)1003 b Fh(CHAPTER)30 b(7.)112 b(CELESTIAL)28 b(COORDINA)-8 b(TE)30 b(SYSTEM)f(R)m(OUTINES)227 555 y Fj(k)m(eyw)m(ord)h(names.)41 b(If)29 b(no)g(additional)f(k)m(eyw) m(ords)i(are)g(to)g(b)s(e)f(excluded,)g(then)g(set)h(nexc)g(=)f(0)h (and)f(sp)s(ecify)227 668 y(NULL)i(for)f(the)g(the)h(**header)g (parameter.)95 890 y Fe(int)47 b(fits_hdr2str)286 1003 y(\(fitsfile)f(*fptr,)g(int)h(nocomments,)d(char)j(**exclist,)e(int)i (nexc,)286 1116 y(>)h(char)e(**header,)g(int)h(*nkeys,)e(int)i (*status\))0 1444 y Ff(7.1)180 b(Self-con)l(tained)46 b(W)l(CS)f(Routines)0 1694 y Fj(The)21 b(follo)m(wing)f(routines)g(DO)h (NOT)g(supp)s(ort)f(the)h(more)h(recen)m(t)g(W)m(CS)f(con)m(v)m(en)m (tions)i(that)e(ha)m(v)m(e)i(b)s(een)e(appro)m(v)m(ed)0 1807 y(as)34 b(part)g(of)g(the)g(FITS)f(standard.)50 b(Consequen)m(tly)-8 b(,)34 b(the)g(follo)m(wing)f(routines)f(ARE)i(NO) m(W)h(DEPRECA)-8 b(TED.)0 1920 y(It)30 b(is)f(STR)m(ONGL)-8 b(Y)30 b(RECOMMENDED)h(that)g(soft)m(w)m(are)g(dev)m(elop)s(ers)e(not)i (use)f(these)g(routines,)f(and)h(instead)0 2033 y(use)g(an)g(external)h (W)m(CS)f(library)-8 b(,)29 b(as)h(describ)s(ed)e(in)i(the)g(previous)f (section.)0 2193 y(These)21 b(routines)f(are)h(included)d(mainly)h(for) i(bac)m(kw)m(ard)g(compatibilit)m(y)f(with)f(existing)h(soft)m(w)m (are.)39 b(They)21 b(supp)s(ort)0 2306 y(the)30 b(follo)m(wing)f (standard)g(map)g(pro)5 b(jections:)40 b(-SIN,)30 b(-T)-8 b(AN,)31 b(-AR)m(C,)g(-NCP)-8 b(,)30 b(-GLS,)g(-MER,)h(and)e(-AIT)h (\(these)0 2419 y(are)f(the)g(legal)f(v)-5 b(alues)28 b(for)g(the)h(co)s(ordt)m(yp)s(e)f(parameter\).)41 b(These)28 b(routines)g(are)h(based)f(on)g(similar)e(functions)h(in)0 2532 y(Classic)i(AIPS.)h(All)f(the)i(angular)e(quan)m(tities)h(are)h (giv)m(en)f(in)f(units)g(of)h(degrees.)0 2754 y Fi(1)81 b Fj(Get)41 b(the)f(v)-5 b(alues)40 b(of)h(the)f(basic)g(set)h(of)f (standard)g(FITS)f(celestial)h(co)s(ordinate)g(system)h(k)m(eyw)m(ords) f(from)227 2867 y(the)33 b(header)f(of)h(a)f(FITS)g(image)h(\(i.e.,)g (the)g(primary)e(arra)m(y)h(or)h(an)f(IMA)m(GE)i(extension\).)46 b(These)33 b(v)-5 b(alues)227 2980 y(ma)m(y)35 b(then)f(b)s(e)g(passed) f(to)i(the)g(\014ts)p 1462 2980 28 4 v 32 w(pix)p 1619 2980 V 31 w(to)p 1730 2980 V 34 w(w)m(orld)e(and)h(\014ts)p 2321 2980 V 32 w(w)m(orld)p 2574 2980 V 32 w(to)p 2686 2980 V 33 w(pix)f(routines)g(that)i(p)s(erform)e(the)227 3093 y(co)s(ordinate)e(transformations.)41 b(If)30 b(an)m(y)h(or)f(all) g(of)h(the)g(W)m(CS)f(k)m(eyw)m(ords)h(are)g(not)g(presen)m(t,)g(then)g (default)227 3206 y(v)-5 b(alues)25 b(will)d(b)s(e)i(returned.)38 b(If)24 b(the)i(\014rst)e(co)s(ordinate)h(axis)f(is)g(the)h (declination-lik)m(e)e(co)s(ordinate,)j(then)f(this)227 3319 y(routine)30 b(will)d(sw)m(ap)k(them)f(so)h(that)g(the)f (longitudinal-lik)m(e)d(co)s(ordinate)j(is)f(returned)h(as)g(the)h (\014rst)e(axis.)227 3463 y(If)35 b(the)h(\014le)e(uses)h(the)g(new)m (er)h('CDj)p 1454 3463 V 32 w(i')f(W)m(CS)g(transformation)g(matrix)g (k)m(eyw)m(ords)g(instead)g(of)g(old)g(st)m(yle)227 3576 y('CDEL)-8 b(Tn')37 b(and)f('CR)m(OT)-8 b(A2')38 b(k)m(eyw)m(ords,)h (then)e(this)e(routine)h(will)e(calculate)k(and)e(return)g(the)h(v)-5 b(alues)227 3689 y(of)33 b(the)g(equiv)-5 b(alen)m(t)33 b(old-st)m(yle)f(k)m(eyw)m(ords.)49 b(Note)34 b(that)g(the)f(con)m(v)m (ersion)g(from)f(the)i(new-st)m(yle)f(k)m(eyw)m(ords)227 3801 y(to)f(the)f(old-st)m(yle)f(v)-5 b(alues)30 b(is)g(sometimes)g (only)g(an)h(appro)m(ximation,)f(so)g(if)g(the)h(appro)m(ximation)f(is) f(larger)227 3914 y(than)37 b(an)h(in)m(ternally)d(de\014ned)h (threshold)g(lev)m(el,)j(then)e(CFITSIO)f(will)f(still)g(return)h(the)i (appro)m(ximate)227 4027 y(W)m(CS)32 b(k)m(eyw)m(ord)h(v)-5 b(alues,)32 b(but)f(will)e(also)j(return)f(with)g(status)h(=)f(APPR)m (O)m(X)p 2908 4027 V 34 w(W)m(CS)p 3149 4027 V 33 w(KEY,)g(to)i(w)m (arn)f(the)227 4140 y(calling)h(program)h(that)h(appro)m(ximations)e (ha)m(v)m(e)i(b)s(een)f(made.)52 b(It)35 b(is)e(then)h(up)f(to)i(the)f (calling)f(program)227 4253 y(to)d(decide)f(whether)f(the)h(appro)m (ximations)f(are)i(su\016cien)m(tly)d(accurate)k(for)e(the)g (particular)e(application,)227 4366 y(or)46 b(whether)e(more)i(precise) f(W)m(CS)g(transformations)g(m)m(ust)g(b)s(e)g(p)s(erformed)f(using)f (new-st)m(yle)j(W)m(CS)227 4479 y(k)m(eyw)m(ords)31 b(directly)-8 b(.)95 4701 y Fe(int)47 b(fits_read_img_coord)c(/)k(ffgics)286 4814 y(\(fitsfile)f(*fptr,)g(>)h(double)f(*xrefval,)g(double)g (*yrefval,)334 4927 y(double)g(*xrefpix,)f(double)i(*yrefpix,)e(double) h(*xinc,)g(double)g(*yinc,)334 5040 y(double)g(*rot,)h(char)f (*coordtype,)f(int)i(*status\))0 5262 y Fi(2)81 b Fj(Get)30 b(the)f(v)-5 b(alues)29 b(of)g(the)h(standard)e(FITS)h(celestial)g(co)s (ordinate)g(system)g(k)m(eyw)m(ords)h(from)f(the)g(header)g(of)h(a)227 5375 y(FITS)23 b(table)h(where)f(the)h(X)g(and)g(Y)g(\(or)g(RA)g(and)f (DEC\))h(co)s(ordinates)g(are)g(stored)g(in)e(2)i(separate)h(columns) 227 5488 y(of)30 b(the)f(table)g(\(as)h(in)e(the)i(Ev)m(en)m(t)g(List)f (table)g(format)g(that)h(is)f(often)g(used)g(b)m(y)g(high)f(energy)h (astroph)m(ysics)227 5601 y(missions\).)69 b(These)40 b(v)-5 b(alues)39 b(ma)m(y)i(then)f(b)s(e)f(passed)h(to)h(the)f(\014ts) p 2511 5601 V 33 w(pix)p 2669 5601 V 31 w(to)p 2780 5601 V 34 w(w)m(orld)f(and)h(\014ts)p 3383 5601 V 32 w(w)m(orld)p 3636 5601 V 32 w(to)p 3748 5601 V 33 w(pix)227 5714 y(routines)30 b(that)g(p)s(erform)f(the)i(co)s(ordinate)f(transformations.)p eop %%Page: 73 81 73 80 bop 0 299 a Fh(7.1.)113 b(SELF-CONT)-8 b(AINED)30 b(W)m(CS)g(R)m(OUTINES)1984 b Fj(73)95 555 y Fe(int)47 b(fits_read_tbl_coord)c(/)k(ffgtcs)286 668 y(\(fitsfile)f(*fptr,)g(int) h(xcol,)f(int)h(ycol,)f(>)i(double)e(*xrefval,)334 781 y(double)g(*yrefval,)f(double)i(*xrefpix,)e(double)h(*yrefpix,)f (double)h(*xinc,)334 894 y(double)g(*yinc,)g(double)g(*rot,)h(char)f (*coordtype,)f(int)i(*status\))0 1154 y Fi(3)81 b Fj(Calculate)40 b(the)i(celestial)e(co)s(ordinate)h(corresp)s(onding)e(to)j(the)f (input)e(X)i(and)g(Y)g(pixel)e(lo)s(cation)i(in)f(the)227 1267 y(image.)95 1526 y Fe(int)47 b(fits_pix_to_world)c(/)48 b(ffwldp)286 1639 y(\(double)e(xpix,)h(double)f(ypix,)g(double)g (xrefval,)g(double)g(yrefval,)334 1752 y(double)g(xrefpix,)g(double)g (yrefpix,)f(double)h(xinc,)h(double)f(yinc,)334 1865 y(double)g(rot,)h(char)f(*coordtype,)f(>)j(double)e(*xpos,)g(double)g (*ypos,)334 1978 y(int)h(*status\))0 2238 y Fi(4)81 b Fj(Calculate)40 b(the)i(X)f(and)f(Y)h(pixel)f(lo)s(cation)g(corresp)s (onding)f(to)j(the)f(input)e(celestial)i(co)s(ordinate)g(in)f(the)227 2351 y(image.)95 2611 y Fe(int)47 b(fits_world_to_pix)c(/)48 b(ffxypx)286 2723 y(\(double)e(xpos,)h(double)f(ypos,)g(double)g (xrefval,)g(double)g(yrefval,)334 2836 y(double)g(xrefpix,)g(double)g (yrefpix,)f(double)h(xinc,)h(double)f(yinc,)334 2949 y(double)g(rot,)h(char)f(*coordtype,)f(>)j(double)e(*xpix,)g(double)g (*ypix,)334 3062 y(int)h(*status\))p eop %%Page: 74 82 74 81 bop 0 299 a Fj(74)1003 b Fh(CHAPTER)30 b(7.)112 b(CELESTIAL)28 b(COORDINA)-8 b(TE)30 b(SYSTEM)f(R)m(OUTINES)p eop %%Page: 75 83 75 82 bop 0 1225 a Fg(Chapter)65 b(8)0 1687 y Fm(Hierarc)-6 b(hical)76 b(Grouping)h(Routines)0 2180 y Fj(These)34 b(functions)g(allo)m(w)g(for)g(the)h(creation)g(and)f(manipulation)e (of)j(FITS)f(HDU)h(Groups,)h(as)f(de\014ned)e(in)g("A)0 2293 y(Hierarc)m(hical)22 b(Grouping)g(Con)m(v)m(en)m(tion)h(for)g (FITS")f(b)m(y)h(Jennings,)g(P)m(ence,)i(F)-8 b(olk)24 b(and)e(Sc)m(hlesinger)g(\()h(h)m(ttp:)37 b(//ad-)0 2406 y(fwww.gsfc.nasa.go)m(v/other/con)m(v)m(ert/group.h)m(tml)27 b(\).)38 b(A)23 b(group)g(is)e(a)j(collection)e(of)h(HDUs)h(whose)e (asso)s(ciation)0 2518 y(is)33 b(de\014ned)f(b)m(y)h(a)h Fa(gr)-5 b(ouping)37 b(table)p Fj(.)50 b(HDUs)35 b(whic)m(h)d(are)i (part)f(of)h(a)g(group)f(are)h(referred)f(to)h(as)g Fa(memb)-5 b(er)36 b(HDUs)0 2631 y Fj(or)i(simply)d(as)i Fa(memb)-5 b(ers)p Fj(.)63 b(Grouping)37 b(table)g(mem)m(b)s(er)g(HDUs)h(ma)m(y)g (themselv)m(es)g(b)s(e)f(grouping)f(tables,)j(th)m(us)0 2744 y(allo)m(wing)29 b(for)h(the)h(construction)f(of)g(op)s(en-ended)g (hierarc)m(hies)f(of)h(HDUs.)0 2904 y(Grouping)25 b(tables)i(con)m (tain)g(one)g(ro)m(w)g(for)f(eac)m(h)i(mem)m(b)s(er)e(HDU.)i(The)e (grouping)f(table)i(columns)e(pro)m(vide)h(iden-)0 3017 y(ti\014cation)h(information)f(that)i(allo)m(ws)f(applications)e(to)j (reference)g(or)g("p)s(oin)m(t)f(to")h(the)g(mem)m(b)s(er)f(HDUs.)40 b(Mem-)0 3130 y(b)s(er)27 b(HDUs)h(are)g(exp)s(ected,)h(but)e(not)h (required,)e(to)j(con)m(tain)f(a)g(set)g(of)g(GRPIDn/GRPLCn)f(k)m(eyw)m (ords)h(in)e(their)0 3243 y(headers)k(for)h(eac)m(h)g(grouping)f(table) g(that)h(they)g(are)g(referenced)g(b)m(y)-8 b(.)41 b(In)30 b(this)g(sense,)h(the)g(GRPIDn/GRPLCn)0 3356 y(k)m(eyw)m(ords)d("link") e(the)i(mem)m(b)s(er)f(HDU)h(bac)m(k)g(to)g(its)f(Grouping)f(table.)40 b(Note)29 b(that)f(a)f(mem)m(b)s(er)g(HDU)h(need)g(not)0 3469 y(reside)h(in)g(the)h(same)g(FITS)f(\014le)h(as)g(its)f(grouping)g (table,)h(and)f(that)i(a)f(giv)m(en)g(HDU)h(ma)m(y)g(b)s(e)e (referenced)h(b)m(y)g(up)0 3582 y(to)h(999)h(grouping)d(tables)h(sim)m (ultaneously)-8 b(.)0 3742 y(Grouping)21 b(tables)i(are)g(implemen)m (ted)e(as)i(FITS)f(binary)f(tables)h(with)g(up)f(to)j(six)d (pre-de\014ned)h(column)f(TTYPEn)0 3855 y(v)-5 b(alues:)35 b('MEMBER)p 752 3855 28 4 v 34 w(XTENSION',)20 b('MEMBER)p 1789 3855 V 33 w(NAME',)h('MEMBER)p 2620 3855 V 34 w(VERSION',)f ('MEMBER)p 3590 3855 V 34 w(POSITION',)0 3968 y('MEMBER)p 451 3968 V 34 w(URI)p 653 3968 V 32 w(TYPE')g(and)g('MEMBER)p 1601 3968 V 34 w(LOCA)-8 b(TION'.)20 b(The)f(\014rst)h(three)g(columns) f(allo)m(w)h(mem)m(b)s(er)g(HDUs)0 4081 y(to)28 b(b)s(e)f(iden)m (ti\014ed)e(b)m(y)i(reference)h(to)g(their)e(XTENSION,)h(EXTNAME)g(and) g(EXTVER)g(k)m(eyw)m(ord)g(v)-5 b(alues.)39 b(The)0 4194 y(fourth)29 b(column)g(allo)m(ws)h(mem)m(b)s(er)f(HDUs)i(to)g(b)s(e)f (iden)m(ti\014ed)e(b)m(y)i(HDU)h(p)s(osition)d(within)g(their)h(FITS)h (\014le.)39 b(The)0 4307 y(last)f(t)m(w)m(o)h(columns)d(iden)m(tify)g (the)i(FITS)f(\014le)g(in)f(whic)m(h)h(the)h(mem)m(b)s(er)f(HDU)h (resides,)h(if)d(di\013eren)m(t)i(from)f(the)0 4419 y(grouping)29 b(table)h(FITS)g(\014le.)0 4580 y(Additional)22 b(user)i(de\014ned)f ("auxiliary")g(columns)g(ma)m(y)i(also)f(b)s(e)g(included)e(with)h(an)m (y)i(grouping)e(table.)38 b(When)25 b(a)0 4693 y(grouping)h(table)i(is) f(copied)g(or)g(mo)s(di\014ed)f(the)i(presence)g(of)f(auxiliary)f (columns)g(is)h(alw)m(a)m(ys)h(tak)m(en)h(in)m(to)e(accoun)m(t)0 4805 y(b)m(y)k(the)g(grouping)f(supp)s(ort)g(functions;)g(ho)m(w)m(ev)m (er,)j(the)e(grouping)f(supp)s(ort)g(functions)f(cannot)j(directly)e (mak)m(e)0 4918 y(use)g(of)h(this)e(data.)0 5079 y(If)44 b(a)h(grouping)e(table)h(column)f(is)h(de\014ned)f(but)h(the)g(corresp) s(onding)f(mem)m(b)s(er)g(HDU)j(information)c(is)i(un-)0 5191 y(a)m(v)-5 b(ailable)38 b(then)f(a)i(n)m(ull)d(v)-5 b(alue)38 b(of)g(the)g(appropriate)g(data)g(t)m(yp)s(e)h(is)e(inserted) g(in)g(the)h(column)f(\014eld.)63 b(In)m(teger)0 5304 y(columns)25 b(\(MEMBER)p 811 5304 V 34 w(POSITION,)g(MEMBER)p 1771 5304 V 34 w(VERSION\))h(are)h(de\014ned)f(with)f(a)i(TNULLn)f(v)-5 b(alue)26 b(of)h(zero)0 5417 y(\(0\).)41 b(Character)27 b(\014eld)e(columns)h(\(MEMBER)p 1607 5417 V 34 w(XTENSION,)g(MEMBER)p 2600 5417 V 33 w(NAME,)i(MEMBER)p 3388 5417 V 34 w(URI)p 3590 5417 V 32 w(TYPE,)0 5530 y(MEMBER)p 426 5530 V 33 w(LOCA)-8 b(TION\))30 b(utilize)f(an)h(ASCI)s(I)f(n)m(ull)f(c)m (haracter)k(to)f(denote)g(a)g(n)m(ull)d(\014eld)h(v)-5 b(alue.)0 5690 y(The)23 b(grouping)f(supp)s(ort)g(functions)g(b)s (elong)h(to)h(t)m(w)m(o)h(basic)e(categories:)39 b(those)24 b(that)h(w)m(ork)e(with)g(grouping)f(table)1905 5942 y(75)p eop %%Page: 76 84 76 83 bop 0 299 a Fj(76)1338 b Fh(CHAPTER)29 b(8.)112 b(HIERAR)m(CHICAL)30 b(GR)m(OUPING)h(R)m(OUTINES)0 555 y Fj(HDUs)26 b(\(\013gt**\))j(and)c(those)h(that)h(w)m(ork)f(with)e (mem)m(b)s(er)i(HDUs)g(\(\013gm**\).)41 b(Tw)m(o)26 b(functions,)g (\014ts)p 3360 555 28 4 v 32 w(cop)m(y)p 3573 555 V 34 w(group\(\))0 668 y(and)40 b(\014ts)p 314 668 V 33 w(remo)m(v)m(e)p 626 668 V 34 w(group\(\),)k(ha)m(v)m(e)e(the)f(option)f(to)i(recursiv)m (ely)d(cop)m(y/delete)k(en)m(tire)e(groups.)71 b(Care)41 b(should)0 781 y(b)s(e)33 b(tak)m(en)h(when)f(emplo)m(ying)f(these)i (functions)e(in)g(recursiv)m(e)h(mo)s(de)g(as)g(p)s(o)s(orly)f (de\014ned)g(groups)h(could)f(cause)0 894 y(unpredictable)23 b(results.)38 b(The)25 b(problem)f(of)i(a)g(grouping)e(table)i (directly)e(or)i(indirectly)d(referencing)i(itself)f(\(th)m(us)0 1007 y(creating)40 b(an)g(in\014nite)d(lo)s(op\))j(is)e(protected)j (against;)k(in)38 b(fact,)44 b(neither)38 b(function)h(will)e(attempt)k (to)f(cop)m(y)h(or)0 1120 y(delete)31 b(an)f(HDU)h(t)m(wice.)0 1453 y Ff(8.1)135 b(Grouping)45 b(T)-11 b(able)45 b(Routines)0 1693 y Fi(1)81 b Fj(Create)34 b(\(app)s(end\))f(a)h(grouping)e(table)i (at)g(the)g(end)f(of)h(the)g(curren)m(t)f(FITS)g(\014le)g(p)s(oin)m (ted)g(to)h(b)m(y)g(fptr.)49 b(The)227 1806 y(grpname)28 b(parameter)h(pro)m(vides)f(the)h(grouping)e(table)h(name)h(\(GRPNAME)g (k)m(eyw)m(ord)g(v)-5 b(alue\))28 b(and)g(ma)m(y)227 1919 y(b)s(e)42 b(set)h(to)g(NULL)f(if)f(no)h(group)g(name)g(is)g(to)h (b)s(e)e(sp)s(eci\014ed.)75 b(The)42 b(groupt)m(yp)s(e)g(parameter)g (sp)s(eci\014es)227 2032 y(the)c(desired)f(structure)g(of)h(the)g (grouping)e(table)i(and)f(ma)m(y)i(tak)m(e)g(on)f(the)g(v)-5 b(alues:)55 b(GT)p 3355 2032 V 33 w(ID)p 3490 2032 V 33 w(ALL)p 3705 2032 V 32 w(URI)227 2145 y(\(all)33 b(columns)f (created\),)k(GT)p 1274 2145 V 33 w(ID)p 1409 2145 V 33 w(REF)d(\(ID)h(b)m(y)g(reference)g(columns\),)f(GT)p 2904 2145 V 33 w(ID)p 3039 2145 V 33 w(POS)f(\(ID)i(b)m(y)g(p)s (osition)227 2258 y(columns\),)47 b(GT)p 801 2258 V 32 w(ID)p 935 2258 V 33 w(ALL)d(\(ID)g(b)m(y)f(reference)i(and)e(p)s (osition)e(columns\),)47 b(GT)p 3028 2258 V 32 w(ID)p 3162 2258 V 33 w(REF)p 3383 2258 V 33 w(URI)d(\(ID)g(b)m(y)227 2371 y(reference)35 b(and)e(FITS)g(\014le)h(URI)f(columns\),)i(and)e (GT)p 2129 2371 V 33 w(ID)p 2264 2371 V 33 w(POS)p 2481 2371 V 32 w(URI)h(\(ID)g(b)m(y)g(p)s(osition)e(and)i(FITS)f(\014le)227 2484 y(URI)e(columns\).)95 2742 y Fe(int)47 b(fits_create_group)c(/)48 b(ffgtcr)286 2855 y(\(fitsfile)e(*fptr,)g(char)g(*grpname,)g(int)h (grouptype,)e(>)i(int)g(*status\))0 3113 y Fi(2)81 b Fj(Create)26 b(\(insert\))f(a)g(grouping)f(table)h(just)g(after)h(the)f (CHDU)h(of)g(the)f(curren)m(t)g(FITS)g(\014le)f(p)s(oin)m(ted)g(to)i(b) m(y)g(fptr.)227 3226 y(All)i(HDUs)h(b)s(elo)m(w)f(the)h(the)g (insertion)e(p)s(oin)m(t)g(will)g(b)s(e)h(shifted)f(do)m(wn)m(w)m(ards) h(to)i(mak)m(e)g(ro)s(om)e(for)g(the)h(new)227 3339 y(HDU.)23 b(The)e(grpname)h(parameter)g(pro)m(vides)e(the)i(grouping)f(table)g (name)h(\(GRPNAME)h(k)m(eyw)m(ord)f(v)-5 b(alue\))227 3451 y(and)25 b(ma)m(y)i(b)s(e)e(set)h(to)h(NULL)e(if)g(no)h(group)f (name)h(is)f(to)h(b)s(e)f(sp)s(eci\014ed.)38 b(The)25 b(groupt)m(yp)s(e)h(parameter)g(sp)s(eci-)227 3564 y(\014es)g(the)h (desired)e(structure)h(of)h(the)f(grouping)f(table)i(and)f(ma)m(y)h (tak)m(e)h(on)e(the)h(v)-5 b(alues:)38 b(GT)p 3355 3564 V 33 w(ID)p 3490 3564 V 33 w(ALL)p 3705 3564 V 32 w(URI)227 3677 y(\(all)33 b(columns)f(created\),)k(GT)p 1274 3677 V 33 w(ID)p 1409 3677 V 33 w(REF)d(\(ID)h(b)m(y)g(reference)g (columns\),)f(GT)p 2904 3677 V 33 w(ID)p 3039 3677 V 33 w(POS)f(\(ID)i(b)m(y)g(p)s(osition)227 3790 y(columns\),)28 b(GT)p 782 3790 V 33 w(ID)p 917 3790 V 33 w(ALL)g(\(ID)g(b)m(y)g (reference)h(and)e(p)s(osition)f(columns\),)i(GT)p 2897 3790 V 33 w(ID)p 3032 3790 V 33 w(REF)p 3253 3790 V 32 w(URI)g(\(ID)h(b)m(y)f(ref-)227 3903 y(erence)g(and)e(FITS)h(\014le)f (URI)h(columns\),)g(and)f(GT)p 1976 3903 V 33 w(ID)p 2111 3903 V 33 w(POS)p 2328 3903 V 32 w(URI)h(\(ID)g(b)m(y)g(p)s (osition)e(and)i(FITS)f(\014le)g(URI)227 4016 y(columns\))k(.)95 4274 y Fe(int)47 b(fits_insert_group)c(/)48 b(ffgtis)286 4387 y(\(fitsfile)e(*fptr,)g(char)g(*grpname,)g(int)h(grouptype,)e(>)i (int)g(*status\))0 4645 y Fi(3)81 b Fj(Change)20 b(the)h(structure)f (of)h(an)g(existing)e(grouping)h(table)g(p)s(oin)m(ted)g(to)h(b)m(y)g (gfptr.)37 b(The)20 b(groupt)m(yp)s(e)g(parameter)227 4758 y(\(see)27 b(\014ts)p 532 4758 V 32 w(create)p 800 4758 V 35 w(group\(\))e(for)h(v)-5 b(alid)24 b(parameter)i(v)-5 b(alues\))25 b(sp)s(eci\014es)g(the)g(new)g(structure)h(of)f(the)h (grouping)227 4871 y(table.)43 b(This)29 b(function)h(only)g(adds)h(or) g(remo)m(v)m(es)h(grouping)e(table)h(columns,)f(it)h(do)s(es)g(not)g (add)g(or)g(delete)227 4984 y(group)26 b(mem)m(b)s(ers)f(\(i.e.,)j (table)e(ro)m(ws\).)40 b(If)26 b(the)g(grouping)f(table)h(already)g (has)g(the)h(desired)d(structure)i(then)227 5097 y(no)35 b(op)s(erations)e(are)i(p)s(erformed)e(and)h(function)f(simply)g (returns)g(with)g(a)i(\(0\))g(success)g(status)g(co)s(de.)53 b(If)227 5210 y(the)32 b(requested)g(structure)g(c)m(hange)h(creates)g (new)f(grouping)f(table)h(columns,)f(then)h(the)g(column)f(v)-5 b(alues)227 5323 y(for)30 b(all)g(existing)f(mem)m(b)s(ers)h(will)d(b)s (e)j(\014lled)e(with)h(the)i(n)m(ull)d(v)-5 b(alues)30 b(appropriate)f(to)i(the)g(column)e(t)m(yp)s(e.)95 5581 y Fe(int)47 b(fits_change_group)c(/)48 b(ffgtch)286 5694 y(\(fitsfile)e(*gfptr,)f(int)i(grouptype,)e(>)j(int)f(*status\))p eop %%Page: 77 85 77 84 bop 0 299 a Fh(8.1.)72 b(GR)m(OUPING)31 b(T)-8 b(ABLE)31 b(R)m(OUTINES)2235 b Fj(77)0 555 y Fi(4)81 b Fj(Remo)m(v)m(e)41 b(the)e(group)g(de\014ned)f(b)m(y)h(the)h (grouping)e(table)h(p)s(oin)m(ted)f(to)i(b)m(y)g(gfptr,)h(and)e (optionally)f(all)g(the)227 668 y(group)29 b(mem)m(b)s(er)f(HDUs.)41 b(The)28 b(rmopt)h(parameter)g(sp)s(eci\014es)f(the)h(action)g(to)h(b)s (e)e(tak)m(en)i(for)f(all)f(mem)m(b)s(ers)227 781 y(of)f(the)g(group)g (de\014ned)e(b)m(y)i(the)g(grouping)f(table.)39 b(V)-8 b(alid)26 b(v)-5 b(alues)26 b(are:)40 b(OPT)p 2848 781 28 4 v 32 w(RM)p 3030 781 V 33 w(GPT)26 b(\(delete)i(only)e(the)227 894 y(grouping)32 b(table\))i(and)f(OPT)p 1259 894 V 32 w(RM)p 1441 894 V 33 w(ALL)g(\(recursiv)m(ely)f(delete)i(all)e(HDUs) i(that)g(b)s(elong)e(to)i(the)g(group\).)227 1007 y(An)m(y)d(groups)g (con)m(taining)g(the)g(grouping)f(table)h(gfptr)f(as)i(a)f(mem)m(b)s (er)g(are)g(up)s(dated,)f(and)h(if)f(rmopt)h(==)227 1120 y(OPT)p 431 1120 V 32 w(RM)p 613 1120 V 33 w(GPT)21 b(all)f(mem)m(b)s (ers)h(ha)m(v)m(e)h(their)e(GRPIDn)h(and)g(GRPLCn)f(k)m(eyw)m(ords)h (up)s(dated)f(accordingly)-8 b(.)227 1233 y(If)36 b(rmopt)g(==)g(OPT)p 985 1233 V 32 w(RM)p 1167 1233 V 33 w(ALL,)g(then)g(other)h(groups)e (that)i(con)m(tain)g(the)f(deleted)g(mem)m(b)s(ers)g(of)g(gfptr)227 1346 y(are)31 b(up)s(dated)e(to)i(re\015ect)g(the)g(deletion)e (accordingly)-8 b(.)95 1582 y Fe(int)47 b(fits_remove_group)c(/)48 b(ffgtrm)286 1695 y(\(fitsfile)e(*gfptr,)f(int)i(rmopt,)f(>)i(int)f (*status\))0 1932 y Fi(5)81 b Fj(Cop)m(y)28 b(\(app)s(end\))g(the)h (group)f(de\014ned)g(b)m(y)h(the)f(grouping)g(table)h(p)s(oin)m(ted)e (to)j(b)m(y)e(infptr,)g(and)g(optionally)f(all)227 2045 y(group)j(mem)m(b)s(er)h(HDUs,)g(to)h(the)f(FITS)f(\014le)f(p)s(oin)m (ted)h(to)i(b)m(y)e(outfptr.)41 b(The)31 b(cp)s(opt)f(parameter)h(sp)s (eci\014es)227 2158 y(the)c(action)g(to)g(b)s(e)f(tak)m(en)h(for)g(all) e(mem)m(b)s(ers)h(of)g(the)h(group)f(infptr.)37 b(V)-8 b(alid)26 b(v)-5 b(alues)25 b(are:)40 b(OPT)p 3443 2158 V 32 w(GCP)p 3674 2158 V 32 w(GPT)227 2271 y(\(cop)m(y)d(only)f(the)g (grouping)f(table\))h(and)f(OPT)p 1887 2271 V 32 w(GCP)p 2118 2271 V 33 w(ALL)h(\(recursiv)m(ely)f(cop)m(y)i(ALL)e(the)i(HDUs)f (that)227 2384 y(b)s(elong)23 b(to)h(the)g(group)f(de\014ned)g(b)m(y)g (infptr\).)37 b(If)23 b(the)h(cp)s(opt)g(==)f(OPT)p 2618 2384 V 32 w(GCP)p 2849 2384 V 32 w(GPT)h(then)f(the)h(mem)m(b)s(ers)f (of)227 2497 y(infptr)h(ha)m(v)m(e)i(their)f(GRPIDn)g(and)g(GRPLCn)g(k) m(eyw)m(ords)h(up)s(dated)e(to)i(re\015ect)g(the)g(existence)g(of)g (the)f(new)227 2610 y(grouping)e(table)g(outfptr,)i(since)e(they)h(no)m (w)g(b)s(elong)f(to)h(the)g(new)g(group.)38 b(If)23 b(cp)s(opt)h(==)f (OPT)p 3460 2610 V 32 w(GCP)p 3691 2610 V 32 w(ALL)227 2723 y(then)29 b(the)g(new)g(grouping)f(table)h(outfptr)f(only)g(con)m (tains)i(p)s(oin)m(ters)e(to)i(the)f(copied)f(mem)m(b)s(er)h(HDUs)h (and)227 2836 y(not)38 b(the)g(original)d(mem)m(b)s(er)i(HDUs)h(of)g (infptr.)60 b(Note)39 b(that,)h(when)d(cp)s(opt)g(==)g(OPT)p 3301 2836 V 32 w(GCP)p 3532 2836 V 33 w(ALL,)g(all)227 2949 y(mem)m(b)s(ers)h(of)h(the)f(group)g(de\014ned)f(b)m(y)i(infptr)d (will)g(b)s(e)h(copied)h(to)h(a)g(single)e(FITS)h(\014le)g(p)s(oin)m (ted)f(to)i(b)m(y)227 3061 y(outfptr)30 b(regardless)g(of)g(their)g (\014le)f(distribution)e(in)i(the)i(original)d(group.)95 3298 y Fe(int)47 b(fits_copy_group)d(/)j(ffgtcp)286 3411 y(\(fitsfile)f(*infptr,)f(fitsfile)h(*outfptr,)f(int)i(cpopt,)f(>)h (int)g(*status\))0 3648 y Fi(6)81 b Fj(Merge)40 b(the)f(t)m(w)m(o)h (groups)e(de\014ned)g(b)m(y)h(the)g(grouping)f(table)g(HDUs)i(infptr)d (and)h(outfptr)h(b)m(y)f(com)m(bining)227 3761 y(their)29 b(mem)m(b)s(ers)g(in)m(to)h(a)g(single)e(grouping)g(table.)41 b(All)28 b(mem)m(b)s(er)h(HDUs)h(\(ro)m(ws\))h(are)f(copied)f(from)g (infptr)227 3874 y(to)f(outfptr.)39 b(If)26 b(mgopt)i(==)e(OPT)p 1419 3874 V 32 w(MR)m(G)p 1669 3874 V 34 w(COPY)g(then)g(infptr)f(con)m (tin)m(ues)i(to)h(exist)f(unaltered)e(after)j(the)227 3987 y(merge.)57 b(If)36 b(the)f(mgopt)i(==)e(OPT)p 1474 3987 V 31 w(MR)m(G)p 1723 3987 V 34 w(MO)m(V)i(then)e(infptr)e(is)i (deleted)h(after)g(the)g(merge.)57 b(In)35 b(b)s(oth)227 4100 y(cases,)d(the)e(GRPIDn)h(and)e(GRPLCn)h(k)m(eyw)m(ords)g(of)h (the)g(mem)m(b)s(er)e(HDUs)i(are)g(up)s(dated)e(accordingly)-8 b(.)95 4337 y Fe(int)47 b(fits_merge_groups)c(/)48 b(ffgtmg)286 4450 y(\(fitsfile)e(*infptr,)f(fitsfile)h(*outfptr,)f(int)i(mgopt,)f(>) h(int)g(*status\))0 4687 y Fi(7)81 b Fj("Compact")24 b(the)f(group)g(de\014ned)f(b)m(y)h(grouping)e(table)i(p)s(oin)m(ted)f (to)i(b)m(y)f(gfptr.)38 b(The)23 b(compaction)g(is)f(ac)m(hiev)m(ed)227 4799 y(b)m(y)37 b(merging)g(\(via)g(\014ts)p 1034 4799 V 32 w(merge)p 1303 4799 V 34 w(groups\(\)\))g(all)f(direct)h(mem)m(b)s (er)g(HDUs)g(of)h(gfptr)e(that)i(are)g(themselv)m(es)227 4912 y(grouping)h(tables.)69 b(The)40 b(cmopt)g(parameter)h(de\014nes)e (whether)g(the)i(merged)f(grouping)e(table)i(HDUs)227 5025 y(remain)j(after)i(merging)e(\(cmopt)i(==)f(OPT)p 1852 5025 V 32 w(CMT)p 2099 5025 V 32 w(MBR\))h(or)f(if)f(they)i(are)f (deleted)g(after)h(merging)227 5138 y(\(cmopt)31 b(==)f(OPT)p 916 5138 V 32 w(CMT)p 1163 5138 V 32 w(MBR)p 1409 5138 V 34 w(DEL\).)g(If)g(the)h(grouping)d(table)j(con)m(tains)f(no)g (direct)g(mem)m(b)s(er)f(HDUs)227 5251 y(that)i(are)f(themselv)m(es)g (grouping)e(tables)i(then)f(this)g(function)f(do)s(es)i(nothing.)39 b(Note)31 b(that)g(this)d(function)227 5364 y(is)i(not)g(recursiv)m(e,) g(i.e.,)h(only)f(the)g(direct)g(mem)m(b)s(er)g(HDUs)h(of)f(gfptr)g(are) h(considered)e(for)h(merging.)95 5601 y Fe(int)47 b(fits_compact_group) c(/)48 b(ffgtcm)286 5714 y(\(fitsfile)e(*gfptr,)f(int)i(cmopt,)f(>)i (int)f(*status\))p eop %%Page: 78 86 78 85 bop 0 299 a Fj(78)1338 b Fh(CHAPTER)29 b(8.)112 b(HIERAR)m(CHICAL)30 b(GR)m(OUPING)h(R)m(OUTINES)0 555 y Fi(8)81 b Fj(V)-8 b(erify)20 b(the)i(in)m(tegrit)m(y)f(of)g(the)g (grouping)f(table)h(p)s(oin)m(ted)f(to)i(b)m(y)f(gfptr)g(to)h(mak)m(e)g (sure)e(that)i(all)e(group)h(mem)m(b)s(ers)227 668 y(are)31 b(accessible)g(and)f(that)h(all)e(links)g(to)i(other)g(grouping)e (tables)i(are)g(v)-5 b(alid.)40 b(The)30 b(\014rstfailed)e(parameter) 227 781 y(returns)e(the)i(mem)m(b)s(er)e(ID)h(\(ro)m(w)h(n)m(um)m(b)s (er\))e(of)i(the)f(\014rst)f(mem)m(b)s(er)h(HDU)h(to)g(fail)e(v)m (eri\014cation)g(\(if)h(p)s(ositiv)m(e)227 894 y(v)-5 b(alue\))35 b(or)f(the)h(\014rst)e(group)h(link)e(to)k(fail)d(\(if)g (negativ)m(e)j(v)-5 b(alue\).)53 b(If)34 b(gfptr)g(is)f(successfully)g (v)m(eri\014ed)g(then)227 1007 y(\014rstfailed)c(con)m(tains)h(a)h (return)e(v)-5 b(alue)30 b(of)h(0.)95 1284 y Fe(int)47 b(fits_verify_group)c(/)48 b(ffgtvf)286 1397 y(\(fitsfile)e(*gfptr,)f (>)j(long)f(*firstfailed,)d(int)j(*status\))0 1674 y Fi(9)81 b Fj(Op)s(en)23 b(a)j(grouping)e(table)h(that)h(con)m(tains)f (the)h(mem)m(b)s(er)e(HDU)i(p)s(oin)m(ted)e(to)i(b)m(y)f(mfptr.)38 b(The)25 b(grouping)f(table)227 1787 y(to)39 b(op)s(en)e(is)g (de\014ned)g(b)m(y)h(the)g(grpid)e(parameter,)k(whic)m(h)d(con)m(tains) h(the)g(k)m(eyw)m(ord)h(index)d(v)-5 b(alue)38 b(of)g(the)227 1900 y(GRPIDn/GRPLCn)d(k)m(eyw)m(ord\(s\))g(that)h(link)d(the)i(mem)m (b)s(er)f(HDU)h(mfptr)f(to)i(the)f(grouping)e(table.)54 b(If)227 2013 y(the)30 b(grouping)e(table)h(resides)f(in)h(a)g(\014le)g (other)g(than)h(the)f(mem)m(b)s(er)g(HDUs)h(\014le)e(then)h(an)h (attempt)g(is)f(\014rst)227 2126 y(made)g(to)h(op)s(en)e(the)h(\014le)f (readwrite,)h(and)f(failing)f(that)j(readonly)-8 b(.)39 b(A)29 b(p)s(oin)m(ter)f(to)i(the)f(op)s(ened)f(grouping)227 2238 y(table)j(HDU)g(is)e(returned)g(in)g(gfptr.)227 2397 y(Note)35 b(that)g(it)e(is)g(p)s(ossible,)f(although)i(unlik)m (ely)d(and)i(undesirable,)f(for)i(the)g(GRPIDn/GRPLCn)f(k)m(ey-)227 2510 y(w)m(ords)k(in)f(a)h(mem)m(b)s(er)g(HDU)h(header)f(to)h(b)s(e)e (non-con)m(tin)m(uous,)j(e.g.,)h(GRPID1,)g(GRPID2,)g(GRPID5,)227 2623 y(GRPID6.)i(In)29 b(suc)m(h)g(cases,)i(the)f(grpid)e(index)g(v)-5 b(alue)30 b(sp)s(eci\014ed)e(in)g(the)i(function)e(call)i(shall)e(iden) m(tify)g(the)227 2736 y(\(grpid\)th)35 b(GRPID)g(v)-5 b(alue.)56 b(In)34 b(the)i(ab)s(o)m(v)m(e)h(example,)f(if)f(grpid)e(==) i(3,)j(then)d(the)g(group)g(sp)s(eci\014ed)f(b)m(y)227 2849 y(GRPID5)d(w)m(ould)f(b)s(e)f(op)s(ened.)95 3126 y Fe(int)47 b(fits_open_group)d(/)j(ffgtop)286 3239 y(\(fitsfile)f (*mfptr,)f(int)i(group,)f(>)i(fitsfile)d(**gfptr,)h(int)h(*status\))0 3516 y Fi(10)f Fj(Add)38 b(a)h(mem)m(b)s(er)f(HDU)i(to)f(an)g(existing) e(grouping)h(table)h(p)s(oin)m(ted)e(to)j(b)m(y)e(gfptr.)66 b(The)38 b(mem)m(b)s(er)g(HDU)227 3629 y(ma)m(y)30 b(either)f(b)s(e)g (p)s(oin)m(ted)f(to)i(mfptr)f(\(whic)m(h)f(m)m(ust)i(b)s(e)e(p)s (ositioned)g(to)i(the)f(mem)m(b)s(er)g(HDU\))i(or,)f(if)e(mfptr)227 3742 y(==)36 b(NULL,)g(iden)m(ti\014ed)e(b)m(y)i(the)g(hdup)s(os)e (parameter)i(\(the)h(HDU)g(p)s(osition)d(n)m(um)m(b)s(er,)i(Primary)e (arra)m(y)227 3855 y(==)g(1\))i(if)e(b)s(oth)g(the)h(grouping)f(table)g (and)h(the)g(mem)m(b)s(er)f(HDU)h(reside)f(in)g(the)h(same)g(FITS)f (\014le.)53 b(The)227 3968 y(new)27 b(mem)m(b)s(er)f(HDU)h(shall)e(ha)m (v)m(e)j(the)f(appropriate)f(GRPIDn)g(and)g(GRPLCn)g(k)m(eyw)m(ords)h (created)h(in)e(its)227 4081 y(header.)44 b(Note)33 b(that)f(if)f(the)h (mem)m(b)s(er)e(HDU)j(is)d(already)h(a)h(mem)m(b)s(er)f(of)h(the)g (group)f(then)g(it)g(will)e(not)j(b)s(e)227 4194 y(added)e(a)h(second)f (time.)95 4471 y Fe(int)47 b(fits_add_group_member)42 b(/)48 b(ffgtam)286 4584 y(\(fitsfile)e(*gfptr,)f(fitsfile)h(*mfptr,)g (int)h(hdupos,)f(>)h(int)g(*status\))0 4938 y Ff(8.2)135 b(Group)45 b(Mem)l(b)t(er)f(Routines)0 5191 y Fi(1)81 b Fj(Return)29 b(the)h(n)m(um)m(b)s(er)f(of)i(mem)m(b)s(er)e(HDUs)i(in) e(a)i(grouping)d(table)j(gfptr.)40 b(The)30 b(n)m(um)m(b)s(er)e(mem)m (b)s(er)i(HDUs)h(is)227 5304 y(just)f(the)h(NAXIS2)f(v)-5 b(alue)30 b(\(n)m(um)m(b)s(er)g(of)g(ro)m(ws\))h(of)f(the)h(grouping)e (table.)95 5581 y Fe(int)47 b(fits_get_num_members)c(/)k(ffgtnm)286 5694 y(\(fitsfile)f(*gfptr,)f(>)j(long)f(*nmembers,)e(int)h(*status\))p eop %%Page: 79 87 79 86 bop 0 299 a Fh(8.2.)72 b(GR)m(OUP)31 b(MEMBER)g(R)m(OUTINES)2295 b Fj(79)0 555 y Fi(2)81 b Fj(Return)34 b(the)h(n)m(um)m(b)s(er)f(of)i (groups)e(to)i(whic)m(h)e(the)h(HDU)h(p)s(oin)m(ted)e(to)i(b)m(y)f (mfptr)f(is)h(link)m(ed,)g(as)g(de\014ned)f(b)m(y)227 668 y(the)27 b(n)m(um)m(b)s(er)f(of)h(GRPIDn/GRPLCn)f(k)m(eyw)m(ord)i (records)e(that)i(app)s(ear)e(in)f(its)i(header.)39 b(Note)28 b(that)g(eac)m(h)227 781 y(time)36 b(this)g(function)f(is)g(called,)j (the)e(indices)f(of)i(the)f(GRPIDn/GRPLCn)g(k)m(eyw)m(ords)h(are)g(c)m (hec)m(k)m(ed)h(to)227 894 y(mak)m(e)29 b(sure)e(they)g(are)h(con)m (tin)m(uous)f(\(ie)h(no)f(gaps\))h(and)f(are)h(re-en)m(umerated)g(to)h (eliminate)d(gaps)i(if)e(found.)95 1228 y Fe(int)47 b (fits_get_num_groups)c(/)k(ffgmng)286 1341 y(\(fitsfile)f(*mfptr,)f(>)j (long)f(*nmembers,)e(int)h(*status\))0 1563 y Fi(3)81 b Fj(Op)s(en)26 b(a)i(mem)m(b)s(er)f(of)h(the)f(grouping)g(table)g(p)s (oin)m(ted)g(to)h(b)m(y)g(gfptr.)39 b(The)27 b(mem)m(b)s(er)g(to)i(op)s (en)e(is)f(iden)m(ti\014ed)g(b)m(y)227 1676 y(its)j(ro)m(w)h(n)m(um)m (b)s(er)e(within)f(the)i(grouping)g(table)g(as)h(giv)m(en)f(b)m(y)h (the)f(parameter)h('mem)m(b)s(er')f(\(\014rst)h(mem)m(b)s(er)227 1788 y(==)g(1\))g(.)41 b(A)30 b(\014ts\014le)e(p)s(oin)m(ter)h(to)i (the)f(op)s(ened)f(mem)m(b)s(er)g(HDU)i(is)e(returned)g(as)h(mfptr.)39 b(Note)31 b(that)g(if)e(the)227 1901 y(mem)m(b)s(er)f(HDU)h(resides)f (in)f(a)i(FITS)f(\014le)f(di\013eren)m(t)h(from)g(the)h(grouping)e (table)h(HDU)i(then)e(the)h(mem)m(b)s(er)227 2014 y(\014le)h(is)f (\014rst)h(op)s(ened)f(readwrite)h(and,)g(failing)e(this,)i(op)s(ened)f (readonly)-8 b(.)95 2236 y Fe(int)47 b(fits_open_member)d(/)j(ffgmop) 286 2349 y(\(fitsfile)f(*gfptr,)f(long)i(member,)f(>)h(fitsfile)f (**mfptr,)f(int)i(*status\))0 2570 y Fi(4)81 b Fj(Cop)m(y)27 b(\(app)s(end\))f(a)i(mem)m(b)s(er)f(HDU)h(of)f(the)h(grouping)d(table) j(p)s(oin)m(ted)e(to)i(b)m(y)f(gfptr.)39 b(The)27 b(mem)m(b)s(er)g(HDU) h(is)227 2683 y(iden)m(ti\014ed)j(b)m(y)i(its)g(ro)m(w)g(n)m(um)m(b)s (er)e(within)g(the)i(grouping)f(table)g(as)i(giv)m(en)f(b)m(y)f(the)i (parameter)f('mem)m(b)s(er')227 2796 y(\(\014rst)j(mem)m(b)s(er)f(==)g (1\).)58 b(The)35 b(cop)m(y)i(of)f(the)g(group)f(mem)m(b)s(er)g(HDU)i (will)c(b)s(e)i(app)s(ended)f(to)j(the)f(FITS)227 2909 y(\014le)28 b(p)s(oin)m(ted)g(to)h(b)m(y)f(mfptr,)h(and)f(up)s(on)f (return)g(mfptr)h(shall)f(p)s(oin)m(t)g(to)j(the)f(copied)f(mem)m(b)s (er)g(HDU.)h(The)227 3022 y(cp)s(opt)e(parameter)h(ma)m(y)g(tak)m(e)h (on)e(the)g(follo)m(wing)f(v)-5 b(alues:)39 b(OPT)p 2465 3022 28 4 v 32 w(MCP)p 2708 3022 V 32 w(ADD)29 b(whic)m(h)d(adds)g(a)i (new)f(en)m(try)227 3135 y(in)c(gfptr)h(for)f(the)i(copied)e(mem)m(b)s (er)h(HDU,)h(OPT)p 1907 3135 V 31 w(MCP)p 2149 3135 V 33 w(NADD)g(whic)m(h)e(do)s(es)h(not)g(add)f(an)h(en)m(try)h(in)d (gfptr)227 3247 y(for)j(the)h(copied)e(mem)m(b)s(er,)i(and)f(OPT)p 1536 3247 V 32 w(MCP)p 1779 3247 V 32 w(REPL)g(whic)m(h)f(replaces)h (the)g(original)e(mem)m(b)s(er)i(en)m(try)g(with)227 3360 y(the)31 b(copied)f(mem)m(b)s(er)f(en)m(try)-8 b(.)95 3582 y Fe(int)47 b(fits_copy_member)d(/)j(ffgmcp)286 3695 y(\(fitsfile)f(*gfptr,)f(fitsfile)h(*mfptr,)g(long)g(member,)g (int)h(cpopt,)f(>)i(int)f(*status\))0 3916 y Fi(5)81 b Fj(T)-8 b(ransfer)34 b(a)i(group)f(mem)m(b)s(er)f(HDU)i(from)f(the)h (grouping)e(table)h(p)s(oin)m(ted)f(to)i(b)m(y)f(infptr)f(to)i(the)f (grouping)227 4029 y(table)h(p)s(oin)m(ted)f(to)i(b)m(y)f(outfptr.)58 b(The)35 b(mem)m(b)s(er)h(HDU)h(to)f(transfer)g(is)f(iden)m(ti\014ed)f (b)m(y)i(its)g(ro)m(w)g(n)m(um)m(b)s(er)227 4142 y(within)k(infptr)g (as)j(sp)s(eci\014ed)e(b)m(y)h(the)h(parameter)g('mem)m(b)s(er')f (\(\014rst)g(mem)m(b)s(er)g(==)f(1\).)78 b(If)42 b(tfopt)h(==)227 4255 y(OPT)p 431 4255 V 32 w(MCP)p 674 4255 V 33 w(ADD)26 b(then)f(the)h(mem)m(b)s(er)e(HDU)i(is)f(made)g(a)h(mem)m(b)s(er)f(of)g (outfptr)g(and)g(remains)f(a)i(mem)m(b)s(er)227 4368 y(of)34 b(infptr.)50 b(If)34 b(tfopt)g(==)g(OPT)p 1339 4368 V 32 w(MCP)p 1582 4368 V 32 w(MO)m(V)h(then)f(the)g(mem)m(b)s(er)f (HDU)i(is)e(deleted)h(from)f(infptr)f(after)227 4481 y(the)f(transfer)f(to)h(outfptr.)95 4702 y Fe(int)47 b(fits_transfer_member)c(/)k(ffgmtf)286 4815 y(\(fitsfile)f(*infptr,)f (fitsfile)h(*outfptr,)f(long)i(member,)e(int)i(tfopt,)334 4928 y(>)h(int)e(*status\))0 5149 y Fi(6)81 b Fj(Remo)m(v)m(e)31 b(a)e(mem)m(b)s(er)g(HDU)h(from)f(the)h(grouping)e(table)h(p)s(oin)m (ted)f(to)i(b)m(y)g(gfptr.)40 b(The)29 b(mem)m(b)s(er)f(HDU)i(to)h(b)s (e)227 5262 y(deleted)36 b(is)e(iden)m(ti\014ed)g(b)m(y)h(its)g(ro)m(w) h(n)m(um)m(b)s(er)f(in)f(the)i(grouping)e(table)h(as)h(sp)s(eci\014ed)e (b)m(y)i(the)f(parameter)227 5375 y('mem)m(b)s(er')41 b(\(\014rst)g(mem)m(b)s(er)g(==)f(1\).)74 b(The)41 b(rmopt)g(parameter) h(ma)m(y)f(tak)m(e)i(on)e(the)h(follo)m(wing)d(v)-5 b(alues:)227 5488 y(OPT)p 431 5488 V 32 w(RM)p 613 5488 V 33 w(ENTR)d(Y)34 b(whic)m(h)d(remo)m(v)m(es)k(the)e(mem)m(b)s(er)g(HDU)h(en)m(try)f (from)g(the)g(grouping)f(table)h(and)g(up-)227 5601 y(dates)40 b(the)f(mem)m(b)s(er's)f(GRPIDn/GRPLCn)g(k)m(eyw)m(ords,)k(and)c(OPT)p 2687 5601 V 32 w(RM)p 2869 5601 V 33 w(MBR)h(whic)m(h)f(remo)m(v)m(es)i (the)227 5714 y(mem)m(b)s(er)30 b(HDU)h(en)m(try)g(from)f(the)g (grouping)f(table)i(and)e(deletes)i(the)f(mem)m(b)s(er)g(HDU)h(itself.) p eop %%Page: 80 88 80 87 bop 0 299 a Fj(80)1338 b Fh(CHAPTER)29 b(8.)112 b(HIERAR)m(CHICAL)30 b(GR)m(OUPING)h(R)m(OUTINES)95 555 y Fe(int)47 b(fits_remove_member)c(/)48 b(ffgmrm)286 668 y(\(fitsfile)e(*fptr,)g(long)g(member,)g(int)h(rmopt,)f(>)i(int)f (*status\))p eop %%Page: 81 89 81 88 bop 0 1225 a Fg(Chapter)65 b(9)0 1687 y Fm(Sp)6 b(ecialized)77 b(CFITSIO)f(In)-6 b(terface)0 1937 y(Routines)0 2429 y Fj(The)28 b(basic)g(in)m(terface)i(routines)e(describ)s(ed)e (previously)h(are)i(recommended)f(for)h(most)g(uses,)g(but)f(the)h (routines)0 2542 y(describ)s(ed)g(in)g(this)h(c)m(hapter)h(are)h(also)e (a)m(v)-5 b(ailable)31 b(if)e(necessary)-8 b(.)43 b(Some)31 b(of)g(these)g(routines)f(p)s(erform)f(more)i(sp)s(e-)0 2655 y(cialized)26 b(function)f(that)j(cannot)f(easily)f(b)s(e)g(done)h (with)e(the)i(basic)g(in)m(terface)g(routines)f(while)e(others)j (duplicate)0 2767 y(the)j(functionalit)m(y)f(of)h(the)g(basic)g (routines)f(but)g(ha)m(v)m(e)i(a)g(sligh)m(tly)d(di\013eren)m(t)i (calling)e(sequence.)41 b(See)31 b(App)s(endix)0 2880 y(B)g(for)f(the)g(de\014nition)e(of)j(eac)m(h)h(function)d(parameter.)0 3210 y Ff(9.1)135 b(FITS)44 b(File)i(Access)e(Routines)0 3446 y Fi(1)81 b Fj(Op)s(en)37 b(an)i(existing)g(FITS)f(\014le)g (residing)f(in)h(core)i(computer)f(memory)-8 b(.)68 b(This)37 b(routine)h(is)h(analogous)g(to)227 3559 y(\014ts)p 354 3559 28 4 v 33 w(op)s(en)p 577 3559 V 32 w(\014le.)54 b(The)35 b('\014lename')f(is)g(curren)m(tly)h(ignored)f(b)m(y)h(this)f (routine)g(and)h(ma)m(y)g(b)s(e)g(an)m(y)g(arbitrary)227 3672 y(string.)77 b(In)42 b(general,)k(the)d(application)e(m)m(ust)i (ha)m(v)m(e)h(preallo)s(cated)e(an)g(initial)e(blo)s(c)m(k)j(of)g (memory)f(to)227 3785 y(hold)h(the)i(FITS)f(\014le)g(prior)f(to)i (calling)e(this)g(routine:)69 b('memptr')44 b(p)s(oin)m(ts)f(to)j(the)e (starting)h(address)227 3898 y(and)39 b('memsize')h(giv)m(es)g(the)g (initial)d(size)i(of)h(the)g(blo)s(c)m(k)f(of)h(memory)-8 b(.)69 b('mem)p 2958 3898 V 33 w(reallo)s(c')39 b(is)g(a)h(p)s(oin)m (ter)e(to)227 4011 y(an)d(optional)g(function)e(that)j(CFITSIO)e(can)h (call)f(to)i(allo)s(cate)g(additional)d(memory)-8 b(,)37 b(if)d(needed)g(\(only)227 4124 y(if)40 b(mo)s(de)f(=)h(READ)m (WRITE\),)i(and)e(is)f(mo)s(deled)g(after)i(the)f(standard)g(C)g ('reallo)s(c')g(function;)k(a)d(n)m(ull)227 4237 y(p)s(oin)m(ter)f(ma)m (y)h(b)s(e)f(giv)m(en)h(if)e(the)i(initial)d(allo)s(cation)i(of)h (memory)f(is)g(all)f(that)i(will)d(b)s(e)i(required)f(\(e.g.,)227 4350 y(if)34 b(the)h(\014le)f(is)g(op)s(ened)g(with)g(mo)s(de)g(=)h (READONL)-8 b(Y\).)36 b(The)e('deltasize')h(parameter)g(ma)m(y)h(b)s(e) e(used)g(to)227 4463 y(suggest)g(a)f(minim)m(um)d(amoun)m(t)j(of)g (additional)e(memory)i(that)g(should)e(b)s(e)h(allo)s(cated)h(during)e (eac)m(h)j(call)227 4575 y(to)d(the)f(memory)f(reallo)s(cation)g (function.)39 b(By)30 b(default,)f(CFITSIO)f(will)f(reallo)s(cate)k (enough)e(additional)227 4688 y(space)44 b(to)g(hold)e(the)i(en)m(tire) f(curren)m(tly)f(de\014ned)h(FITS)f(\014le)h(\(as)g(giv)m(en)h(b)m(y)f (the)h(NAXISn)e(k)m(eyw)m(ords\))227 4801 y(or)g(1)f(FITS)g(blo)s(c)m (k)g(\(=)g(2880)i(b)m(ytes\),)i(whic)m(h)c(ev)m(er)h(is)e(larger.)73 b(V)-8 b(alues)42 b(of)f(deltasize)g(less)g(than)g(2880)227 4914 y(will)28 b(b)s(e)i(ignored.)41 b(Since)30 b(the)h(memory)g (reallo)s(cation)f(op)s(eration)g(can)h(b)s(e)f(computationally)f(exp)s (ensiv)m(e,)227 5027 y(allo)s(cating)24 b(a)h(larger)f(initial)e(blo)s (c)m(k)i(of)h(memory)-8 b(,)26 b(and/or)f(sp)s(ecifying)d(a)j(larger)g (deltasize)f(v)-5 b(alue)24 b(ma)m(y)h(help)227 5140 y(to)31 b(reduce)g(the)f(n)m(um)m(b)s(er)f(of)i(reallo)s(cation)e (calls)h(and)g(mak)m(e)h(the)g(application)d(program)i(run)f(faster.)95 5375 y Fe(int)47 b(fits_open_memfile)c(/)48 b(ffomem)286 5488 y(\(fitsfile)e(**fptr,)f(const)i(char)f(*filename,)f(int)i(mode,)g (void)f(**memptr,)334 5601 y(size_t)g(*memsize,)f(size_t)i(deltasize,) 334 5714 y(void)g(*\(*mem_realloc\)\(void)42 b(*p,)47 b(size_t)f(newsize\),)f(int)i(*status\))1905 5942 y Fj(81)p eop %%Page: 82 90 82 89 bop 0 299 a Fj(82)1003 b Fh(CHAPTER)30 b(9.)112 b(SPECIALIZED)28 b(CFITSIO)h(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)0 555 y Fi(2)81 b Fj(Create)49 b(a)g(new)f(FITS)g(\014le)g(residing)e(in) i(core)h(computer)g(memory)-8 b(.)96 b(This)47 b(routine)g(is)h (analogous)h(to)227 668 y(\014ts)p 354 668 28 4 v 33 w(create)p 623 668 V 34 w(\014le.)39 b(In)29 b(general,)h(the)f (application)e(m)m(ust)i(ha)m(v)m(e)i(preallo)s(cated)e(an)g(initial)d (blo)s(c)m(k)j(of)g(memory)227 781 y(to)38 b(hold)d(the)i(FITS)f (\014le)g(prior)f(to)i(calling)f(this)f(routine:)53 b('memptr')36 b(p)s(oin)m(ts)g(to)h(the)g(starting)g(address)227 894 y(and)i('memsize')h(giv)m(es)g(the)g(initial)d(size)i(of)h(the)g(blo)s (c)m(k)f(of)h(memory)-8 b(.)69 b('mem)p 2958 894 V 33 w(reallo)s(c')39 b(is)g(a)h(p)s(oin)m(ter)e(to)227 1007 y(an)g(optional)e(function)g(that)i(CFITSIO)e(can)i(call)f(to)h(allo)s (cate)g(additional)d(memory)-8 b(,)40 b(if)c(needed,)k(and)227 1120 y(is)33 b(mo)s(deled)f(after)i(the)g(standard)f(C)g('reallo)s(c')g (function;)h(a)g(n)m(ull)d(p)s(oin)m(ter)i(ma)m(y)h(b)s(e)f(giv)m(en)g (if)g(the)h(initial)227 1233 y(allo)s(cation)f(of)g(memory)g(is)g(all)f (that)i(will)c(b)s(e)j(required.)47 b(The)33 b('deltasize')h(parameter) f(ma)m(y)h(b)s(e)f(used)f(to)227 1346 y(suggest)i(a)f(minim)m(um)d (amoun)m(t)j(of)g(additional)e(memory)i(that)g(should)e(b)s(e)h(allo)s (cated)h(during)e(eac)m(h)j(call)227 1458 y(to)d(the)f(memory)f(reallo) s(cation)g(function.)39 b(By)30 b(default,)f(CFITSIO)f(will)f(reallo)s (cate)k(enough)e(additional)227 1571 y(space)k(to)g(hold)e(1)h(FITS)g (blo)s(c)m(k)f(\(=)h(2880)i(b)m(ytes\))f(and)f(v)-5 b(alues)31 b(of)i(deltasize)f(less)f(than)h(2880)i(will)29 b(b)s(e)j(ig-)227 1684 y(nored.)39 b(Since)24 b(the)i(memory)f(reallo)s(cation)f(op)s (eration)h(can)h(b)s(e)f(computationally)f(exp)s(ensiv)m(e,)i(allo)s (cating)227 1797 y(a)h(larger)f(initial)d(blo)s(c)m(k)j(of)g(memory)-8 b(,)28 b(and/or)e(sp)s(ecifying)e(a)i(larger)g(deltasize)g(v)-5 b(alue)26 b(ma)m(y)h(help)d(to)j(reduce)227 1910 y(the)k(n)m(um)m(b)s (er)e(of)h(reallo)s(cation)g(calls)g(and)f(mak)m(e)j(the)e(application) f(program)h(run)f(faster.)95 2147 y Fe(int)47 b(fits_create_memfile)c (/)k(ffimem)286 2260 y(\(fitsfile)f(**fptr,)f(void)i(**memptr,)334 2373 y(size_t)f(*memsize,)f(size_t)i(deltasize,)334 2486 y(void)g(*\(*mem_realloc\)\(void)42 b(*p,)47 b(size_t)f(newsize\),)f (int)i(*status\))0 2723 y Fi(3)81 b Fj(Reop)s(en)34 b(a)i(FITS)e (\014le)g(that)i(w)m(as)f(previously)e(op)s(ened)i(with)e(\014ts)p 2414 2723 V 33 w(op)s(en)p 2637 2723 V 32 w(\014le)h(or)h(\014ts)p 3058 2723 V 33 w(create)p 3327 2723 V 34 w(\014le.)54 b(The)34 b(new)227 2836 y(\014ts\014le)h(p)s(oin)m(ter)h(ma)m(y)h(then) f(b)s(e)f(treated)j(as)e(a)h(separate)g(\014le,)g(and)f(one)h(ma)m(y)g (sim)m(ultaneously)d(read)i(or)227 2949 y(write)d(to)i(2)f(\(or)g (more\))g(di\013eren)m(t)f(extensions)g(in)g(the)h(same)g(\014le.)50 b(The)33 b(\014ts)p 2886 2949 V 32 w(op)s(en)p 3108 2949 V 32 w(\014le)g(routine)g(\(ab)s(o)m(v)m(e\))227 3061 y(automatically)i(detects)i(cases)f(where)e(a)i(previously)d(op)s(ened) h(\014le)h(is)f(b)s(eing)g(op)s(ened)g(again,)j(and)d(then)227 3174 y(in)m(ternally)29 b(call)g(\014ts)p 930 3174 V 33 w(reop)s(en)p 1229 3174 V 32 w(\014le,)h(so)g(programs)g(should)f (rarely)g(need)h(to)h(explicitly)d(call)i(this)f(routine.)95 3411 y Fe(int)47 b(fits_reopen_file)d(/)j(ffreopen)286 3524 y(\(fitsfile)f(*openfptr,)f(fitsfile)g(**newfptr,)g(>)j(int)f (*status\))0 3761 y Fi(4)81 b Fj(Create)24 b(a)g(new)f(FITS)g(\014le,)h (using)e(a)i(template)g(\014le)e(to)j(de\014ne)d(its)h(initial)e(size)j (and)f(structure.)37 b(The)24 b(template)227 3874 y(ma)m(y)i(b)s(e)f (another)g(FITS)g(HDU)h(or)f(an)g(ASCI)s(I)f(template)i(\014le.)38 b(If)25 b(the)g(input)f(template)h(\014le)g(name)g(p)s(oin)m(ter)227 3987 y(is)i(n)m(ull,)g(then)g(this)g(routine)f(b)s(eha)m(v)m(es)j(the)f (same)g(as)g(\014ts)p 2160 3987 V 32 w(create)p 2428 3987 V 35 w(\014le.)39 b(The)27 b(curren)m(tly)g(supp)s(orted)f(format) 227 4100 y(of)33 b(the)g(ASCI)s(I)e(template)i(\014le)e(is)h(describ)s (ed)e(under)h(the)i(\014ts)p 2350 4100 V 33 w(parse)p 2591 4100 V 32 w(template)g(routine)f(\(in)f(the)i(general)227 4213 y(Utilities)c(section\))95 4450 y Fe(int)47 b (fits_create_template)c(/)k(fftplt)286 4563 y(\(fitsfile)f(**fptr,)f (char)i(*filename,)e(char)i(*tpltfile)e(>)i(int)g(*status\))0 4799 y Fi(5)81 b Fj(P)m(arse)28 b(the)f(input)f(\014lename)g(or)i(URL)f (in)m(to)g(its)g(comp)s(onen)m(t)h(parts:)39 b(the)27 b(\014le)g(t)m(yp)s(e)h(\(\014le://,)g(ftp://,)h(h)m(ttp://,)227 4912 y(etc\),)34 b(the)e(base)g(input)d(\014le)i(name,)h(the)g(name)g (of)g(the)g(output)f(\014le)g(that)h(the)g(input)e(\014le)g(is)h(to)h (b)s(e)f(copied)227 5025 y(to)38 b(prior)d(to)i(op)s(ening,)g(the)g (HDU)g(or)f(extension)h(sp)s(eci\014cation,)g(the)g(\014ltering)d(sp)s (eci\014er,)j(the)g(binning)227 5138 y(sp)s(eci\014er,)27 b(and)h(the)g(column)f(sp)s(eci\014er.)38 b(Null)26 b(strings)h(will)e (b)s(e)j(returned)f(for)g(an)m(y)i(comp)s(onen)m(ts)f(that)h(are)227 5251 y(not)i(presen)m(t)f(in)f(the)i(input)d(\014le)i(name.)95 5488 y Fe(int)47 b(fits_parse_input_url)c(/)k(ffiurl)286 5601 y(\(char)g(*filename,)e(>)i(char)g(*filetype,)e(char)h(*infile,)g (char)h(*outfile,)e(char)334 5714 y(*extspec,)g(char)i(*filter,)f(char) g(*binspec,)f(char)i(*colspec,)e(int)i(*status\))p eop %%Page: 83 91 83 90 bop 0 299 a Fh(9.1.)72 b(FITS)30 b(FILE)g(A)m(CCESS)f(R)m (OUTINES)2244 b Fj(83)0 555 y Fi(6)81 b Fj(P)m(arse)33 b(the)f(input)f(\014lename)h(and)f(return)h(the)h(HDU)g(n)m(um)m(b)s (er)e(that)i(w)m(ould)e(b)s(e)h(mo)m(v)m(ed)i(to)f(if)e(the)i(\014le)e (w)m(ere)227 668 y(op)s(ened)i(with)f(\014ts)p 878 668 28 4 v 32 w(op)s(en)p 1100 668 V 32 w(\014le.)48 b(The)33 b(returned)f(HDU)i(n)m(um)m(b)s(er)e(b)s(egins)g(with)g(1)h(for)g(the)g (primary)f(arra)m(y)-8 b(,)227 781 y(so)40 b(for)f(example,)j(if)c(the) i(input)d(\014lename)i(=)g(`m)m(y\014le.\014ts[2]')h(then)f(hdun)m(um)e (=)i(3)h(will)d(b)s(e)i(returned.)227 894 y(CFITSIO)j(do)s(es)i(not)g (op)s(en)f(the)g(\014le)g(to)i(c)m(hec)m(k)g(if)d(the)i(extension)g (actually)f(exists)g(if)g(an)g(extension)227 1007 y(n)m(um)m(b)s(er)e (is)h(sp)s(eci\014ed.)74 b(If)42 b(an)g(extension)g(name)g(is)g (included)d(in)i(the)i(\014le)e(name)h(sp)s(eci\014cation)f(\(e.g.)227 1120 y(`m)m(y\014le.\014ts[EVENTS]')j(then)f(this)g(routine)g(will)f (ha)m(v)m(e)j(to)f(op)s(en)g(the)g(FITS)f(\014le)g(and)g(lo)s(ok)h(for) g(the)227 1233 y(p)s(osition)29 b(of)h(the)h(named)f(extension,)h(then) f(close)h(\014le)e(again.)41 b(This)29 b(is)g(not)i(p)s(ossible)d(if)i (the)g(\014le)g(is)f(b)s(eing)227 1346 y(read)34 b(from)f(the)h(stdin)e (stream,)j(and)f(an)f(error)g(will)f(b)s(e)h(returned)f(in)h(this)f (case.)52 b(If)33 b(the)h(\014lename)f(do)s(es)227 1458 y(not)42 b(sp)s(ecify)f(an)h(explicit)e(extension)i(\(e.g.)76 b('m)m(y\014le.\014ts'\))42 b(then)g(hdun)m(um)e(=)h(-99)i(will)d(b)s (e)h(returned,)227 1571 y(whic)m(h)34 b(is)g(functionally)f(equiv)-5 b(alen)m(t)34 b(to)i(hdun)m(um)d(=)h(1.)55 b(This)33 b(routine)h(is)g(mainly)g(used)g(for)g(bac)m(kw)m(ard)227 1684 y(compatibilit)m(y)h(in)h(the)g(fto)s(ols)h(soft)m(w)m(are)h(pac)m (k)-5 b(age)39 b(and)d(is)f(not)i(recommended)g(for)f(general)h(use.)59 b(It)37 b(is)227 1797 y(generally)i(b)s(etter)g(and)g(more)g(e\016cien) m(t)h(to)g(\014rst)e(op)s(en)h(the)g(FITS)g(\014le)f(with)g(\014ts)p 3125 1797 V 32 w(op)s(en)p 3347 1797 V 33 w(\014le,)i(then)f(use)227 1910 y(\014ts)p 354 1910 V 33 w(get)p 507 1910 V 34 w(hdu)p 694 1910 V 31 w(n)m(um)c(to)i(determine)f(whic)m(h)f(HDU)i(in)e(the)i (\014le)e(has)h(b)s(een)g(op)s(ened,)h(rather)f(than)g(calling)227 2023 y(\014ts)p 354 2023 V 33 w(parse)p 595 2023 V 32 w(input)p 841 2023 V 31 w(url)29 b(follo)m(w)m(ed)h(b)m(y)g(a)h(call)e (to)j(\014ts)p 1967 2023 V 32 w(op)s(en)p 2189 2023 V 32 w(\014le.)143 2280 y Fe(int)47 b(fits_parse_extnum)c(/)48 b(ffextn)334 2393 y(\(char)e(*filename,)f(>)j(int)f(*hdunum,)e(int)i (*status\))0 2650 y Fi(7)81 b Fj(P)m(arse)45 b(the)g(input)d(\014le)i (name)h(and)f(return)f(the)i(ro)s(ot)g(\014le)f(name.)83 b(The)44 b(ro)s(ot)h(name)g(includes)d(the)j(\014le)227 2763 y(t)m(yp)s(e)35 b(if)f(sp)s(eci\014ed,)h(\(e.g.)56 b('ftp://')37 b(or)e('h)m(ttp://'\))i(and)d(the)h(full)e(path)i(name,)h (to)g(the)f(exten)m(t)i(that)e(it)g(is)227 2875 y(sp)s(eci\014ed)25 b(in)f(the)j(input)d(\014lename.)38 b(It)26 b(do)s(es)g(not)g(include)e (the)i(HDU)h(name)f(or)g(n)m(um)m(b)s(er,)g(or)g(an)m(y)h(\014ltering) 227 2988 y(sp)s(eci\014cations.)143 3245 y Fe(int)47 b(fits_parse_rootname)c(/)k(ffrtnm)334 3358 y(\(char)f(*filename,)f(>)j (char)f(*rootname,)e(int)h(*status\);)0 3615 y Fi(8)81 b Fj(T)-8 b(est)37 b(if)e(the)i(input)e(\014le)h(or)g(a)h(compressed)g (v)m(ersion)f(of)h(the)g(\014le)e(\(with)h(a)h(.gz,)j(.Z,)c(.z,)j(or)e (.zip)f(extension\))227 3728 y(exists)i(on)g(disk.)62 b(The)37 b(returned)g(v)-5 b(alue)37 b(of)h(the)h('exists')f(parameter) g(will)d(ha)m(v)m(e)40 b(1)e(of)g(the)g(4)g(follo)m(wing)227 3841 y(v)-5 b(alues:)370 4087 y Fe(2:)95 b(the)47 b(file)g(does)g(not)f (exist,)h(but)f(a)i(compressed)d(version)h(does)g(exist)370 4200 y(1:)95 b(the)47 b(disk)g(file)g(does)f(exist)370 4313 y(0:)95 b(neither)46 b(the)h(file)g(nor)g(a)g(compressed)e (version)h(of)h(the)g(file)g(exist)323 4426 y(-1:)94 b(the)47 b(input)g(file)f(name)h(is)g(not)g(a)g(disk)g(file)g(\(could)f (be)h(a)g(ftp,)g(http,)561 4539 y(smem,)g(or)g(mem)g(file,)f(or)h(a)h (file)e(piped)h(in)g(on)g(the)g(STDIN)f(stream\))143 4892 y(int)h(fits_file_exists)c(/)48 b(ffexist)334 5005 y(\(char)e(*filename,)f(>)j(int)f(*exists,)e(int)i(*status\);)0 5262 y Fi(9)81 b Fj(Flush)35 b(an)m(y)j(in)m(ternal)e(bu\013ers)g(of)i (data)g(to)g(the)f(output)g(FITS)g(\014le.)61 b(These)37 b(routines)f(rarely)g(need)h(to)i(b)s(e)227 5375 y(called,)g(but)d(can) i(b)s(e)f(useful)e(in)h(cases)j(where)d(other)i(pro)s(cesses)f(need)g (to)h(access)h(the)f(same)f(FITS)g(\014le)227 5488 y(in)i(real)i(time,) h(either)e(on)h(disk)e(or)h(in)f(memory)-8 b(.)71 b(These)41 b(routines)e(also)h(help)f(to)j(ensure)d(that)i(if)f(the)227 5601 y(application)34 b(program)g(subsequen)m(tly)g(ab)s(orts)g(then)h (the)g(FITS)f(\014le)g(will)e(ha)m(v)m(e)37 b(b)s(een)d(closed)g(prop)s (erly)-8 b(.)227 5714 y(The)43 b(\014rst)g(routine,)j(\014ts)p 1110 5714 V 33 w(\015ush)p 1332 5714 V 31 w(\014le)c(is)h(more)g (rigorous)g(and)g(completely)g(closes,)k(then)d(reop)s(ens,)i(the)p eop %%Page: 84 92 84 91 bop 0 299 a Fj(84)1003 b Fh(CHAPTER)30 b(9.)112 b(SPECIALIZED)28 b(CFITSIO)h(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)227 555 y Fj(curren)m(t)h(HDU,)h(b)s(efore)e(\015ushing)f(the)i(in)m (ternal)e(bu\013ers,)h(th)m(us)h(ensuring)e(that)i(the)g(output)g(FITS) f(\014le)g(is)227 668 y(iden)m(tical)35 b(to)h(what)f(w)m(ould)g(b)s(e) g(pro)s(duced)f(if)g(the)i(FITS)f(w)m(as)h(closed)f(at)h(that)g(p)s (oin)m(t)f(\(i.e.,)i(with)e(a)h(call)227 781 y(to)g(\014ts)p 470 781 28 4 v 33 w(close)p 690 781 V 33 w(\014le\).)55 b(The)35 b(second)g(routine,)h(\014ts)p 1912 781 V 33 w(\015ush)p 2134 781 V 31 w(bu\013er)e(simply)f(\015ushes)h(the)h(in)m (ternal)f(CFITSIO)227 894 y(bu\013ers)28 b(of)h(data)h(to)f(the)h (output)e(FITS)g(\014le,)h(without)f(up)s(dating)f(and)h(closing)g(the) h(curren)m(t)g(HDU.)h(This)227 1007 y(is)36 b(m)m(uc)m(h)h(faster,)i (but)e(there)g(ma)m(y)g(b)s(e)f(circumstances)h(where)f(the)h (\015ushed)f(\014le)g(do)s(es)g(not)h(completely)227 1120 y(re\015ect)31 b(the)g(\014nal)e(state)j(of)e(the)h(\014le)e(as)i (it)f(will)d(exist)k(when)e(the)h(\014le)g(is)f(actually)h(closed.)227 1266 y(A)h(t)m(ypical)f(use)g(of)h(these)g(routines)e(w)m(ould)g(b)s(e) h(to)h(\015ush)e(the)h(state)i(of)f(a)g(FITS)e(table)i(to)g(disk)e (after)i(eac)m(h)227 1379 y(ro)m(w)36 b(of)f(the)h(table)f(is)f (written.)54 b(It)36 b(is)e(recommend)h(that)h(\014ts)p 2392 1379 V 32 w(\015ush)p 2613 1379 V 32 w(\014le)e(b)s(e)h(called)f (after)i(the)f(\014rst)g(ro)m(w)227 1492 y(is)j(written,)i(then)e (\014ts)p 1023 1492 V 32 w(\015ush)p 1244 1492 V 31 w(bu\013er)g(ma)m (y)h(b)s(e)f(called)f(after)i(eac)m(h)h(subsequen)m(t)e(ro)m(w)g(is)g (written.)64 b(Note)227 1605 y(that)40 b(this)e(latter)h(routine)f (will)e(not)j(automatically)g(up)s(date)f(the)h(NAXIS2)g(k)m(eyw)m(ord) h(whic)m(h)d(records)227 1718 y(the)d(n)m(um)m(b)s(er)d(of)i(ro)m(ws)h (of)f(data)g(in)f(the)h(table,)h(so)g(this)e(k)m(eyw)m(ord)h(m)m(ust)g (b)s(e)f(explicitly)f(up)s(dated)h(b)m(y)h(the)227 1831 y(application)c(program)h(after)h(eac)m(h)h(ro)m(w)e(is)f(written.)95 2067 y Fe(int)47 b(fits_flush_file)d(/)j(ffflus)286 2180 y(\(fitsfile)f(*fptr,)g(>)h(int)g(*status\))95 2406 y(int)g (fits_flush_buffer)c(/)48 b(ffflsh)286 2519 y(\(fitsfile)e(*fptr,)g(0,) h(>)g(int)g(*status\))286 2745 y(\(Note:)94 b(The)47 b(second)f(argument)g(must)g(be)i(0\).)0 3075 y Ff(9.2)135 b(HDU)46 b(Access)e(Routines)0 3311 y Fi(1)81 b Fj(Get)28 b(the)f(b)m(yte)h(o\013sets)g(in)e(the)h(FITS)f(\014le)h(to)g(the)h (start)g(of)f(the)g(header)g(and)g(the)g(start)h(and)e(end)h(of)g(the)g (data)227 3424 y(in)33 b(the)h(CHDU.)g(The)f(di\013erence)g(b)s(et)m(w) m(een)i(headstart)f(and)f(dataend)h(equals)f(the)h(size)f(of)h(the)g (CHDU.)227 3537 y(If)e(the)h(CHDU)f(is)g(the)g(last)g(HDU)h(in)e(the)i (\014le,)f(then)g(dataend)g(is)f(also)i(equal)e(to)i(the)g(size)f(of)h (the)f(en)m(tire)227 3650 y(FITS)25 b(\014le.)38 b(Null)24 b(p)s(oin)m(ters)g(ma)m(y)i(b)s(e)f(input)e(for)j(an)m(y)f(of)h(the)g (address)e(parameters)i(if)f(their)f(v)-5 b(alues)25 b(are)h(not)227 3763 y(needed.)54 b(The)34 b(\014ts)p 897 3763 V 32 w(get)p 1049 3763 V 34 w(hduaddr)e(routine)i(is)g (obsolete)h(and)f(should)f(no)i(longer)f(b)s(e)g(used.)53 b(The)34 b(new)m(er)227 3876 y(\014ts)p 354 3876 V 33 w(get)p 507 3876 V 34 w(hduo\013)24 b(routine)h(uses)g(the)h('o\013)p 1588 3876 V 33 w(t')g(data)h(t)m(yp)s(e)f(whic)m(h)e(can)i(supp)s(ort)e (o\013sets)i(in)e(large)i(\014les)f(greater)227 3988 y(than)30 b(2.1GB)j(in)c(size.)95 4225 y Fe(int)47 b(fits_get_hduoff)d (/)j(ffghof)334 4338 y(\(fitsfile)e(*fptr,)h(>)i(off_t)e(*headstart,)f (off_t)h(*datastart,)f(off_t)h(*dataend,)382 4451 y(int)h(*status\))95 4676 y(int)g(fits_get_hduaddr)d(/)j(ffghad)94 b(\(OBSOLETE)45 b(routine\))334 4789 y(\(fitsfile)g(*fptr,)h(>)i(long)f(*headstart,)d (long)j(*datastart,)e(long)h(*dataend,)382 4902 y(int)h(*status\))0 5139 y Fi(2)81 b Fj(Create)31 b(\(app)s(end\))f(a)i(new)e(empt)m(y)i (HDU)f(at)h(the)f(end)f(of)i(the)f(FITS)f(\014le.)41 b(This)30 b(is)g(no)m(w)h(the)g(CHDU)g(but)f(it)227 5252 y(is)h(completely)f(empt)m(y)i(and)f(has)g(no)g(header)g(k)m(eyw)m (ords.)43 b(It)32 b(is)e(recommended)h(that)h(\014ts)p 3344 5252 V 32 w(create)p 3612 5252 V 34 w(img)f(or)227 5365 y(\014ts)p 354 5365 V 33 w(create)p 623 5365 V 34 w(tbl)e(b)s(e)h(used)g(instead)f(of)i(this)e(routine.)95 5601 y Fe(int)47 b(fits_create_hdu)d(/)j(ffcrhd)286 5714 y(\(fitsfile)f(*fptr,)g(>)h(int)g(*status\))p eop %%Page: 85 93 85 92 bop 0 299 a Fh(9.2.)72 b(HDU)31 b(A)m(CCESS)e(R)m(OUTINES)2488 b Fj(85)0 555 y Fi(3)81 b Fj(Insert)22 b(a)h(new)g(IMA)m(GE)h (extension)e(immediately)g(follo)m(wing)f(the)i(CHDU,)h(or)f(insert)f (a)h(new)f(Primary)g(Arra)m(y)227 668 y(at)30 b(the)e(b)s(eginning)e (of)j(the)g(\014le.)39 b(An)m(y)29 b(follo)m(wing)e(extensions)h(in)g (the)g(\014le)g(will)e(b)s(e)i(shifted)f(do)m(wn)i(to)g(mak)m(e)227 781 y(ro)s(om)36 b(for)h(the)f(new)g(extension.)58 b(If)36 b(the)h(CHDU)g(is)e(the)i(last)f(HDU)h(in)e(the)i(\014le)e(then)h(the)h (new)f(image)227 894 y(extension)30 b(will)e(simply)f(b)s(e)j(app)s (ended)e(to)j(the)f(end)g(of)g(the)g(\014le.)40 b(One)30 b(can)g(force)h(a)g(new)e(primary)f(arra)m(y)227 1007 y(to)35 b(b)s(e)d(inserted)h(at)h(the)g(b)s(eginning)d(of)i(the)h(FITS) f(\014le)f(b)m(y)i(setting)g(status)f(=)h(PREPEND)p 3432 1007 28 4 v 32 w(PRIMAR)-8 b(Y)227 1120 y(prior)24 b(to)h(calling)f (the)h(routine.)37 b(In)25 b(this)e(case)j(the)f(old)f(primary)f(arra)m (y)j(will)c(b)s(e)i(con)m(v)m(erted)j(to)e(an)g(IMA)m(GE)227 1233 y(extension.)48 b(The)32 b(new)g(extension)h(\(or)g(primary)e (arra)m(y\))i(will)e(b)s(ecome)i(the)g(CHDU.)g(Refer)g(to)h(Chapter)227 1346 y(9)d(for)f(a)h(list)e(of)h(pre-de\014ned)f(bitpix)g(v)-5 b(alues.)95 1605 y Fe(int)47 b(fits_insert_img)d(/)j(ffiimg)286 1718 y(\(fitsfile)f(*fptr,)g(int)h(bitpix,)e(int)i(naxis,)f(long)h (*naxes,)f(>)h(int)g(*status\))0 1978 y Fi(4)81 b Fj(Insert)30 b(a)g(new)g(ASCI)s(I)f(or)i(binary)e(table)h(extension)g(immediately)f (follo)m(wing)g(the)i(CHDU.)g(An)m(y)f(follo)m(wing)227 2091 y(extensions)35 b(will)e(b)s(e)i(shifted)f(do)m(wn)h(to)h(mak)m(e) g(ro)s(om)g(for)f(the)g(new)g(extension.)56 b(If)35 b(there)h(are)f(no) h(other)227 2204 y(follo)m(wing)29 b(extensions)i(then)f(the)h(new)f (table)g(extension)h(will)d(simply)g(b)s(e)i(app)s(ended)f(to)i(the)g (end)f(of)h(the)227 2317 y(\014le.)41 b(If)30 b(the)h(FITS)f(\014le)f (is)h(curren)m(tly)g(empt)m(y)h(then)f(this)f(routine)h(will)e(create)k (a)f(dumm)m(y)f(primary)e(arra)m(y)227 2430 y(b)s(efore)j(app)s(ending) e(the)j(table)g(to)g(it.)43 b(The)31 b(new)g(extension)h(will)c(b)s (ecome)k(the)g(CHDU.)g(The)f(tunit)g(and)227 2543 y(extname)39 b(parameters)g(are)f(optional)g(and)g(a)g(n)m(ull)e(p)s(oin)m(ter)i(ma) m(y)g(b)s(e)g(giv)m(en)g(if)f(they)i(are)f(not)h(de\014ned.)227 2656 y(When)32 b(inserting)e(an)i(ASCI)s(I)f(table)h(with)e(\014ts)p 1847 2656 V 33 w(insert)p 2104 2656 V 32 w(atbl,)i(a)g(n)m(ull)e(p)s (oin)m(ter)h(ma)m(y)i(giv)m(en)f(for)g(the)g(*tb)s(col)227 2769 y(parameter)23 b(in)e(whic)m(h)h(case)h(eac)m(h)h(column)d(of)i (the)g(table)f(will)e(b)s(e)i(separated)h(b)m(y)f(a)h(single)e(space)i (c)m(haracter.)227 2882 y(Similarly)-8 b(,)25 b(if)g(the)i(input)e(v)-5 b(alue)26 b(of)h(ro)m(wlen)f(is)f(0,)j(then)f(CFITSIO)e(will)f (calculate)j(the)g(default)e(ro)m(wlength)227 2994 y(based)40 b(on)h(the)g(tb)s(col)e(and)h(tt)m(yp)s(e)h(v)-5 b(alues.)71 b(When)40 b(inserting)f(a)i(binary)d(table)j(with)e(\014ts)p 3430 2994 V 32 w(insert)p 3686 2994 V 32 w(btbl,)227 3107 y(if)g(there)i(are)f(follo)m(wing)f(extensions)h(in)f(the)h (\014le)f(and)h(if)f(the)h(table)g(con)m(tains)h(v)-5 b(ariable)39 b(length)g(arra)m(y)227 3220 y(columns)28 b(then)h(p)s(coun)m(t)g(m)m(ust)g(sp)s(ecify)f(the)i(exp)s(ected)g (\014nal)e(size)h(of)g(the)h(data)g(heap,)g(otherwise)e(p)s(coun)m(t) 227 3333 y(m)m(ust)j(=)f(0.)95 3593 y Fe(int)47 b(fits_insert_atbl)d(/) j(ffitab)286 3706 y(\(fitsfile)f(*fptr,)g(long)g(rowlen,)g(long)h (nrows,)f(int)h(tfields,)e(char)i(*ttype[],)334 3819 y(long)g(*tbcol,)f(char)g(*tform[],)f(char)i(*tunit[],)e(char)i (*extname,)e(>)j(int)f(*status\))95 4045 y(int)g(fits_insert_btbl)d(/)j (ffibin)286 4158 y(\(fitsfile)f(*fptr,)g(long)g(nrows,)g(int)h (tfields,)f(char)h(**ttype,)286 4271 y(char)g(**tform,)f(char)g (**tunit,)g(char)g(*extname,)g(long)g(pcount,)g(>)i(int)e(*status\))0 4530 y Fi(5)81 b Fj(Mo)s(dify)26 b(the)i(size,)g(dimensions,)e(and/or)h (data)i(t)m(yp)s(e)f(of)f(the)h(curren)m(t)g(primary)d(arra)m(y)j(or)g (image)g(extension.)227 4643 y(If)39 b(the)h(new)e(image,)43 b(as)c(sp)s(eci\014ed)f(b)m(y)h(the)g(input)f(argumen)m(ts,)k(is)c (larger)h(than)g(the)h(curren)m(t)f(existing)227 4756 y(image)29 b(in)e(the)h(FITS)g(\014le)f(then)h(zero)h(\014ll)d(data)j (will)d(b)s(e)i(inserted)f(at)i(the)f(end)g(of)g(the)h(curren)m(t)f (image)h(and)227 4869 y(an)m(y)35 b(follo)m(wing)e(extensions)h(will)e (b)s(e)i(mo)m(v)m(ed)i(further)d(bac)m(k)i(in)f(the)g(\014le.)53 b(Similarly)-8 b(,)32 b(if)i(the)h(new)f(image)227 4982 y(is)i(smaller)f(than)i(the)f(curren)m(t)h(image)g(then)f(an)m(y)h (follo)m(wing)e(extensions)h(will)e(b)s(e)i(shifted)g(up)f(to)m(w)m (ards)227 5095 y(the)h(b)s(eginning)d(of)j(the)g(FITS)f(\014le)g(and)g (the)h(image)g(data)g(will)e(b)s(e)h(truncated)g(to)i(the)f(new)f (size.)57 b(This)227 5208 y(routine)26 b(rewrites)g(the)i(BITPIX,)f (NAXIS,)g(and)f(NAXISn)g(k)m(eyw)m(ords)i(with)e(the)h(appropriate)f(v) -5 b(alues)26 b(for)227 5321 y(the)31 b(new)f(image.)95 5581 y Fe(int)47 b(fits_resize_img)d(/)j(ffrsim)286 5694 y(\(fitsfile)f(*fptr,)g(int)h(bitpix,)e(int)i(naxis,)f(long)h(*naxes,)f (>)h(int)g(*status\))p eop %%Page: 86 94 86 93 bop 0 299 a Fj(86)1003 b Fh(CHAPTER)30 b(9.)112 b(SPECIALIZED)28 b(CFITSIO)h(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)0 555 y Fi(6)81 b Fj(Cop)m(y)43 b(the)h(data)h(\(and)e(not)h(the)g (header\))g(from)f(the)h(CHDU)g(asso)s(ciated)g(with)f(infptr)e(to)k (the)f(CHDU)227 668 y(asso)s(ciated)33 b(with)e(outfptr.)47 b(This)31 b(will)e(o)m(v)m(erwrite)k(an)m(y)g(data)g(previously)e(in)g (the)i(output)f(CHDU.)h(This)227 781 y(lo)m(w)38 b(lev)m(el)g(routine)f (is)g(used)g(b)m(y)h(\014ts)p 1510 781 28 4 v 33 w(cop)m(y)p 1724 781 V 33 w(hdu,)h(but)e(it)h(ma)m(y)g(also)g(b)s(e)g(useful)e(in)h (certain)h(application)227 894 y(programs)30 b(that)h(w)m(an)m(t)g(to)g (cop)m(y)g(the)f(data)h(from)f(one)h(FITS)e(\014le)h(to)h(another)f (but)f(also)i(w)m(an)m(t)g(to)g(mo)s(dify)227 1007 y(the)h(header)g(k)m (eyw)m(ords.)46 b(The)32 b(required)e(FITS)h(header)h(k)m(eyw)m(ords)g (whic)m(h)f(de\014ne)g(the)h(structure)g(of)g(the)227 1120 y(HDU)f(m)m(ust)g(b)s(e)e(written)h(to)h(the)f(output)g(CHDU)h(b)s (efore)f(calling)f(this)g(routine.)95 1369 y Fe(int)47 b(fits_copy_data)d(/)k(ffcpdt)286 1482 y(\(fitsfile)e(*infptr,)f (fitsfile)h(*outfptr,)f(>)i(int)g(*status\))0 1732 y Fi(7)81 b Fj(This)33 b(routine)g(forces)i(CFITSIO)f(to)h(rescan)g(the)g (curren)m(t)g(header)f(k)m(eyw)m(ords)h(that)g(de\014ne)f(the)h (structure)227 1845 y(of)f(the)f(HDU)h(\(suc)m(h)g(as)f(the)h(NAXIS)f (and)g(BITPIX)g(k)m(eyw)m(ords\))h(so)f(that)h(it)f(reinitializes)e (the)i(in)m(ternal)227 1958 y(bu\013ers)26 b(that)h(describ)s(e)f(the)h (HDU)g(structure.)39 b(This)25 b(routine)h(is)g(useful)f(for)h (reinitializing)d(the)k(structure)227 2071 y(of)34 b(an)f(HDU)h(if)e (an)m(y)i(of)g(the)f(required)f(k)m(eyw)m(ords)h(\(e.g.,)j(NAXISn\))d (ha)m(v)m(e)i(b)s(een)e(mo)s(di\014ed.)47 b(In)33 b(practice)227 2184 y(it)d(should)e(rarely)h(b)s(e)g(necessary)h(to)h(call)e(this)g (routine)g(b)s(ecause)g(CFITSIO)g(in)m(ternally)f(calls)h(it)g(in)g (most)227 2297 y(situations.)95 2546 y Fe(int)47 b(fits_set_hdustruc)c (/)48 b(ffrdef)286 2659 y(\(fitsfile)e(*fptr,)g(>)h(int)g(*status\))141 b(\(DEPRECATED\))0 2991 y Ff(9.3)135 b(Sp)t(ecialized)46 b(Header)g(Keyw)l(ord)f(Routines)0 3245 y Fd(9.3.1)112 b(Header)38 b(Information)f(Routines)0 3452 y Fi(1)81 b Fj(Reserv)m(e)29 b(space)g(in)d(the)j(CHU)f(for)g(MOREKEYS)f(more)h (header)g(k)m(eyw)m(ords.)41 b(This)26 b(routine)h(ma)m(y)i(b)s(e)f (called)227 3565 y(to)34 b(allo)s(cate)f(space)g(for)f(additional)f(k)m (eyw)m(ords)i(at)g(the)g(time)f(the)h(header)f(is)g(created)h(\(prior)f (to)h(writing)227 3678 y(an)m(y)h(data\).)51 b(CFITSIO)32 b(can)i(dynamically)d(add)i(more)g(space)h(to)g(the)g(header)f(when)f (needed,)j(ho)m(w)m(ev)m(er)227 3791 y(it)30 b(is)g(more)g(e\016cien)m (t)h(to)g(preallo)s(cate)f(the)h(required)e(space)i(if)e(the)h(size)h (is)e(kno)m(wn)h(in)f(adv)-5 b(ance.)95 4041 y Fe(int)47 b(fits_set_hdrsize)d(/)j(ffhdef)286 4153 y(\(fitsfile)f(*fptr,)g(int)h (morekeys,)e(>)i(int)g(*status\))0 4403 y Fi(2)81 b Fj(Return)26 b(the)h(n)m(um)m(b)s(er)e(of)j(k)m(eyw)m(ords)f(in)e(the)i(header)g (\(not)h(coun)m(ting)f(the)g(END)g(k)m(eyw)m(ord\))h(and)e(the)h (curren)m(t)227 4516 y(p)s(osition)32 b(in)h(the)h(header.)50 b(The)34 b(p)s(osition)d(is)i(the)h(n)m(um)m(b)s(er)f(of)h(the)g(k)m (eyw)m(ord)g(record)f(that)i(will)c(b)s(e)i(read)227 4629 y(next)k(\(or)g(one)f(greater)i(than)e(the)h(p)s(osition)d(of)j (the)g(last)f(k)m(eyw)m(ord)h(that)g(w)m(as)g(read\).)59 b(A)37 b(v)-5 b(alue)35 b(of)i(1)g(is)227 4742 y(returned)29 b(if)h(the)g(p)s(oin)m(ter)g(is)f(p)s(ositioned)g(at)i(the)f(b)s (eginning)e(of)i(the)h(header.)95 4992 y Fe(int)47 b(fits_get_hdrpos)d (/)j(ffghps)286 5105 y(\(fitsfile)f(*fptr,)g(>)h(int)g(*keysexist,)e (int)i(*keynum,)e(int)i(*status\))0 5394 y Fd(9.3.2)112 b(Read)38 b(and)h(W)-9 b(rite)35 b(the)i(Required)g(Keyw)m(ords)0 5601 y Fi(1)81 b Fj(W)-8 b(rite)20 b(the)h(primary)d(header)i(or)g(IMA) m(GE)i(extension)e(k)m(eyw)m(ords)g(in)m(to)g(the)h(CHU.)f(The)g (simpler)e(\014ts)p 3535 5601 V 32 w(write)p 3770 5601 V 32 w(imghdr)227 5714 y(routine)32 b(is)h(equiv)-5 b(alen)m(t)32 b(to)i(calling)e(\014ts)p 1604 5714 V 32 w(write)p 1839 5714 V 32 w(grphdr)f(with)h(the)i(default)e(v)-5 b(alues)32 b(of)i(simple)d(=)i(TR)m(UE,)p eop %%Page: 87 95 87 94 bop 0 299 a Fh(9.3.)72 b(SPECIALIZED)29 b(HEADER)i(KEYW)m(ORD)g (R)m(OUTINES)1510 b Fj(87)227 555 y(p)s(coun)m(t)39 b(=)g(0,)j(gcoun)m (t)e(=)f(1,)j(and)c(extend)h(=)g(TR)m(UE.)g(The)g(PCOUNT,)g(GCOUNT)f (and)h(EXTEND)227 668 y(k)m(eyw)m(ords)32 b(are)f(not)g(required)f(in)f (the)i(primary)f(header)g(and)h(are)g(only)f(written)g(if)g(p)s(coun)m (t)h(is)f(not)h(equal)227 781 y(to)26 b(zero,)h(gcoun)m(t)f(is)e(not)i (equal)e(to)i(zero)g(or)f(one,)h(and)f(if)f(extend)h(is)f(TR)m(UE,)h (resp)s(ectiv)m(ely)-8 b(.)39 b(When)25 b(writing)227 894 y(to)37 b(an)f(IMA)m(GE)h(extension,)h(the)e(SIMPLE)f(and)h(EXTEND) g(parameters)g(are)h(ignored.)57 b(It)36 b(is)f(recom-)227 1007 y(mended)27 b(that)i(\014ts)p 885 1007 28 4 v 33 w(create)p 1154 1007 V 34 w(image)g(or)f(\014ts)p 1680 1007 V 32 w(create)p 1948 1007 V 35 w(tbl)f(b)s(e)g(used)h(instead)f (of)i(these)f(routines)f(to)i(write)f(the)227 1120 y(required)h(header) h(k)m(eyw)m(ords.)95 1374 y Fe(int)47 b(fits_write_imghdr)c(/)48 b(ffphps)286 1487 y(\(fitsfile)e(*fptr,)g(int)h(bitpix,)e(int)i(naxis,) f(long)h(*naxes,)f(>)h(int)g(*status\))95 1713 y(int)g (fits_write_grphdr)c(/)48 b(ffphpr)286 1826 y(\(fitsfile)e(*fptr,)g (int)h(simple,)e(int)i(bitpix,)f(int)h(naxis,)f(long)h(*naxes,)334 1939 y(long)g(pcount,)f(long)g(gcount,)g(int)h(extend,)f(>)h(int)g (*status\))0 2194 y Fi(2)81 b Fj(W)-8 b(rite)29 b(the)h(ASCI)s(I)d (table)j(header)f(k)m(eyw)m(ords)g(in)m(to)h(the)f(CHU.)h(The)e (optional)h(TUNITn)f(and)h(EXTNAME)227 2307 y(k)m(eyw)m(ords)f(are)h (written)d(only)h(if)g(the)h(input)e(p)s(oin)m(ters)h(are)h(not)g(n)m (ull.)38 b(A)27 b(n)m(ull)f(p)s(oin)m(ter)h(ma)m(y)h(giv)m(en)g(for)g (the)227 2419 y(*tb)s(col)36 b(parameter)h(in)e(whic)m(h)g(case)j(a)e (single)f(space)i(will)d(b)s(e)i(inserted)f(b)s(et)m(w)m(een)i(eac)m(h) g(column)e(of)i(the)227 2532 y(table.)56 b(Similarly)-8 b(,)33 b(if)i(ro)m(wlen)f(is)h(giv)m(en)g(=)g(0,)i(then)e(CFITSIO)f (will)f(calculate)i(the)h(default)e(ro)m(wlength)227 2645 y(based)c(on)h(the)f(tb)s(col)g(and)g(tt)m(yp)s(e)h(v)-5 b(alues.)95 2900 y Fe(int)47 b(fits_write_atblhdr)c(/)48 b(ffphtb)286 3013 y(\(fitsfile)e(*fptr,)g(long)g(rowlen,)g(long)h (nrows,)f(int)h(tfields,)e(char)i(**ttype,)334 3126 y(long)g(*tbcol,)f (char)g(**tform,)g(char)g(**tunit,)g(char)h(*extname,)e(>)i(int)g (*status\))0 3380 y Fi(3)81 b Fj(W)-8 b(rite)29 b(the)g(binary)f(table) h(header)f(k)m(eyw)m(ords)i(in)m(to)f(the)g(CHU.)g(The)g(optional)f (TUNITn)g(and)h(EXTNAME)227 3493 y(k)m(eyw)m(ords)35 b(are)g(written)f(only)g(if)f(the)i(input)e(p)s(oin)m(ters)g(are)i(not) g(n)m(ull.)51 b(The)35 b(p)s(coun)m(t)f(parameter,)i(whic)m(h)227 3606 y(sp)s(eci\014es)g(the)h(size)f(of)h(the)g(v)-5 b(ariable)36 b(length)g(arra)m(y)h(heap,)h(should)d(initially)e(=)k(0;) j(CFITSIO)c(will)e(au-)227 3719 y(tomatically)d(up)s(date)g(the)g (PCOUNT)f(k)m(eyw)m(ord)i(v)-5 b(alue)31 b(if)f(an)m(y)h(v)-5 b(ariable)30 b(length)h(arra)m(y)h(data)g(is)e(written)227 3832 y(to)h(the)e(heap.)41 b(The)29 b(TF)m(ORM)g(k)m(eyw)m(ord)h(v)-5 b(alue)29 b(for)h(v)-5 b(ariable)28 b(length)h(v)m(ector)i(columns)d (should)g(ha)m(v)m(e)j(the)227 3945 y(form)c('Pt\(len\)')i(or)e ('1Pt\(len\)')i(where)e(`t')h(is)f(the)h(data)g(t)m(yp)s(e)g(co)s(de)f (letter)h(\(A,I,J,E,D,)h(etc.\))42 b(and)27 b(`len')g(is)227 4058 y(an)h(in)m(teger)h(sp)s(ecifying)d(the)i(maxim)m(um)f(length)g (of)i(the)f(v)m(ectors)h(in)e(that)i(column)e(\(len)g(m)m(ust)h(b)s(e)g (greater)227 4171 y(than)36 b(or)g(equal)g(to)h(the)f(longest)h(v)m (ector)g(in)e(the)i(column\).)57 b(If)36 b(`len')f(is)h(not)g(sp)s (eci\014ed)f(when)g(the)h(table)227 4284 y(is)31 b(created)h(\(e.g.,)h (the)f(input)d(TF)m(ORMn)i(v)-5 b(alue)31 b(is)f(just)h('1Pt'\))i(then) e(CFITSIO)f(will)e(scan)k(the)f(column)227 4397 y(when)f(the)h(table)g (is)f(\014rst)g(closed)g(and)h(will)d(app)s(end)h(the)i(maxim)m(um)f (length)g(to)h(the)g(TF)m(ORM)g(k)m(eyw)m(ord)227 4509 y(v)-5 b(alue.)40 b(Note)30 b(that)f(if)e(the)i(table)f(is)g(subsequen) m(tly)f(mo)s(di\014ed)f(to)k(increase)e(the)h(maxim)m(um)e(length)h(of) h(the)227 4622 y(v)m(ectors)39 b(then)e(the)g(mo)s(difying)e(program)i (is)f(resp)s(onsible)f(for)i(also)g(up)s(dating)e(the)j(TF)m(ORM)f(k)m (eyw)m(ord)227 4735 y(v)-5 b(alue.)95 4990 y Fe(int)47 b(fits_write_btblhdr)c(/)48 b(ffphbn)286 5103 y(\(fitsfile)e(*fptr,)g (long)g(nrows,)g(int)h(tfields,)f(char)h(**ttype,)334 5216 y(char)g(**tform,)e(char)i(**tunit,)e(char)i(*extname,)e(long)i (pcount,)f(>)h(int)g(*status\))0 5470 y Fi(4)81 b Fj(Read)30 b(the)h(required)d(k)m(eyw)m(ords)j(from)f(the)h(CHDU)f(\(image)i(or)e (table\).)41 b(When)30 b(reading)g(from)g(an)g(IMA)m(GE)227 5583 y(extension)23 b(the)h(SIMPLE)e(and)h(EXTEND)g(parameters)h(are)f (ignored.)38 b(A)23 b(n)m(ull)e(p)s(oin)m(ter)i(ma)m(y)h(b)s(e)e (supplied)227 5696 y(for)30 b(an)m(y)h(of)g(the)f(returned)f (parameters)i(that)g(are)g(not)f(needed.)p eop %%Page: 88 96 88 95 bop 0 299 a Fj(88)1003 b Fh(CHAPTER)30 b(9.)112 b(SPECIALIZED)28 b(CFITSIO)h(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)95 555 y Fe(int)47 b(fits_read_imghdr)d(/)j(ffghpr)286 668 y(\(fitsfile)f(*fptr,)g(int)h(maxdim,)e(>)j(int)f(*simple,)e(int)i (*bitpix,)f(int)h(*naxis,)334 781 y(long)g(*naxes,)f(long)g(*pcount,)g (long)g(*gcount,)g(int)h(*extend,)e(int)i(*status\))95 1007 y(int)g(fits_read_atblhdr)c(/)48 b(ffghtb)286 1120 y(\(fitsfile)e(*fptr,int)f(maxdim,)h(>)h(long)g(*rowlen,)e(long)i (*nrows,)334 1233 y(int)g(*tfields,)e(char)i(**ttype,)e(long)i(*tbcol,) f(char)h(**tform,)e(char)i(**tunit,)334 1346 y(char)g(*extname,)93 b(int)47 b(*status\))95 1571 y(int)g(fits_read_btblhdr)c(/)48 b(ffghbn)286 1684 y(\(fitsfile)e(*fptr,)g(int)h(maxdim,)e(>)j(long)f (*nrows,)e(int)i(*tfields,)334 1797 y(char)g(**ttype,)e(char)i (**tform,)e(char)i(**tunit,)f(char)g(*extname,)334 1910 y(long)h(*pcount,)e(int)i(*status\))0 2197 y Fd(9.3.3)112 b(W)-9 b(rite)36 b(Keyw)m(ord)h(Routines)0 2416 y Fj(These)32 b(routines)g(simply)e(app)s(end)h(a)h(new)g(k)m(eyw)m(ord)h(to)h(the)e (header)h(and)f(do)g(not)h(c)m(hec)m(k)h(to)f(see)g(if)f(a)g(k)m(eyw)m (ord)0 2528 y(with)c(the)h(same)h(name)f(already)g(exists.)40 b(In)28 b(general)h(it)g(is)f(preferable)g(to)i(use)f(the)h(\014ts)p 3009 2528 28 4 v 32 w(up)s(date)p 3317 2528 V 32 w(k)m(ey)g(routine)e (to)0 2641 y(ensure)34 b(that)h(the)g(same)g(k)m(eyw)m(ord)g(is)e(not)i (written)f(more)h(than)f(once)h(to)h(the)e(header.)54 b(See)34 b(App)s(endix)e(B)j(for)0 2754 y(the)c(de\014nition)d(of)i (the)h(parameters)f(used)g(in)f(these)i(routines.)0 2988 y Fi(1)81 b Fj(W)-8 b(rite)29 b(\(app)s(end\))g(a)g(new)g(k)m(eyw)m (ord)h(of)g(the)f(appropriate)f(data)i(t)m(yp)s(e)g(in)m(to)f(the)h (CHU.)f(A)h(n)m(ull)d(p)s(oin)m(ter)h(ma)m(y)227 3101 y(b)s(e)35 b(en)m(tered)h(for)f(the)h(commen)m(t)h(parameter,)g(whic)m (h)d(will)f(cause)j(the)g(commen)m(t)g(\014eld)e(of)i(the)f(k)m(eyw)m (ord)227 3214 y(to)43 b(b)s(e)e(left)h(blank.)75 b(The)41 b(\015t,)k(dbl,)e(cmp,)i(and)d(dblcmp)e(v)m(ersions)h(of)h(this)f (routine)g(ha)m(v)m(e)i(the)g(added)227 3327 y(feature)33 b(that)g(if)f(the)g('decimals')g(parameter)h(is)f(negativ)m(e,)i(then)e (the)h('G')g(displa)m(y)e(format)i(rather)f(then)227 3440 y(the)i('E')f(format)h(will)c(b)s(e)j(used)f(when)g(constructing)h (the)h(k)m(eyw)m(ord)f(v)-5 b(alue,)34 b(taking)f(the)h(absolute)e(v)-5 b(alue)227 3553 y(of)34 b('decimals')f(for)g(the)h(precision.)49 b(This)32 b(will)f(suppress)g(trailing)h(zeros,)j(and)e(will)e(use)j(a) g(\014xed)f(format)227 3666 y(rather)e(than)f(an)g(exp)s(onen)m(tial)f (format,)i(dep)s(ending)d(on)i(the)h(magnitude)e(of)i(the)g(v)-5 b(alue.)95 3899 y Fe(int)47 b(fits_write_key_str)c(/)48 b(ffpkys)286 4012 y(\(fitsfile)e(*fptr,)g(char)g(*keyname,)g(char)g (*value,)g(char)h(*comment,)334 4125 y(>)h(int)e(*status\))95 4351 y(int)h(fits_write_key_[log,)c(lng])j(/)95 b(ffpky[lj])286 4464 y(\(fitsfile)46 b(*fptr,)g(char)g(*keyname,)g(DTYPE)g(numval,)g (char)g(*comment,)334 4577 y(>)i(int)e(*status\))95 4803 y(int)h(fits_write_key_[flt,)c(dbl,)j(fixflg,)g(fixdbl])g(/)h (ffpky[edfg])286 4916 y(\(fitsfile)f(*fptr,)g(char)g(*keyname,)g(DTYPE) g(numval,)g(int)h(decimals,)286 5028 y(char)g(*comment,)e(>)j(int)f (*status\))95 5254 y(int)g(fits_write_key_[cmp,)c(dblcmp,)i(fixcmp,)h (fixdblcmp])f(/)j(ffpk[yc,ym,fc,fm])286 5367 y(\(fitsfile)e(*fptr,)g (char)g(*keyname,)g(DTYPE)g(*numval,)g(int)g(decimals,)286 5480 y(char)h(*comment,)e(>)j(int)f(*status\))0 5714 y Fi(2)81 b Fj(W)-8 b(rite)29 b(\(app)s(end\))f(a)i(string)e(v)-5 b(alued)28 b(k)m(eyw)m(ord)i(in)m(to)f(the)g(CHU)h(whic)m(h)d(ma)m(y)j (b)s(e)f(longer)g(than)f(68)i(c)m(haracters)p eop %%Page: 89 97 89 96 bop 0 299 a Fh(9.3.)72 b(SPECIALIZED)29 b(HEADER)i(KEYW)m(ORD)g (R)m(OUTINES)1510 b Fj(89)227 555 y(in)42 b(length.)79 b(This)41 b(uses)i(the)g(Long)h(String)d(Keyw)m(ord)i(con)m(v)m(en)m (tion)i(that)e(is)g(describ)s(ed)e(in)h(the`Lo)s(cal)227 668 y(FITS)c(Con)m(v)m(en)m(tions')h(section)g(in)f(Chapter)g(4.)66 b(Since)37 b(this)h(uses)g(a)h(non-standard)f(FITS)g(con)m(v)m(en)m (tion)227 781 y(to)45 b(enco)s(de)f(the)g(long)g(k)m(eyw)m(ord)g (string,)j(programs)c(whic)m(h)g(use)h(this)f(routine)g(should)f(also)h (call)h(the)227 894 y(\014ts)p 354 894 28 4 v 33 w(write)p 590 894 V 32 w(k)m(ey)p 755 894 V 33 w(longw)m(arn)25 b(routine)f(to)i(add)f(some)h(COMMENT)f(k)m(eyw)m(ords)g(to)h(w)m(arn)f (users)g(of)g(the)h(FITS)227 1007 y(\014le)42 b(that)i(this)d(con)m(v)m (en)m(tion)j(is)e(b)s(eing)f(used.)78 b(The)42 b(\014ts)p 2220 1007 V 32 w(write)p 2455 1007 V 32 w(k)m(ey)p 2620 1007 V 34 w(longw)m(arn)g(routine)g(also)h(writes)f(a)227 1120 y(k)m(eyw)m(ord)29 b(called)e(LONGSTRN)g(to)i(record)f(the)g(v)m (ersion)g(of)g(the)g(longstring)f(con)m(v)m(en)m(tion)i(that)g(has)f(b) s(een)227 1233 y(used,)35 b(in)e(case)j(a)f(new)e(con)m(v)m(en)m(tion)j (is)e(adopted)g(at)h(some)g(p)s(oin)m(t)e(in)h(the)g(future.)52 b(If)34 b(the)h(LONGSTRN)227 1346 y(k)m(eyw)m(ord)43 b(is)f(already)g(presen)m(t)h(in)f(the)g(header,)k(then)d(\014ts)p 2332 1346 V 32 w(write)p 2567 1346 V 32 w(k)m(ey)p 2732 1346 V 34 w(longw)m(arn)f(will)e(simply)g(return)227 1458 y(without)30 b(doing)f(an)m(ything.)95 1700 y Fe(int)47 b(fits_write_key_longstr)42 b(/)48 b(ffpkls)286 1813 y(\(fitsfile)e(*fptr,)g(char)g(*keyname,)g(char)g(*longstr,)g(char)g (*comment,)334 1926 y(>)i(int)e(*status\))95 2151 y(int)h (fits_write_key_longwarn)42 b(/)47 b(ffplsw)286 2264 y(\(fitsfile)f(*fptr,)g(>)h(int)g(*status\))0 2506 y Fi(3)81 b Fj(W)-8 b(rite)37 b(\(app)s(end\))e(a)i(n)m(um)m(b)s(ered)e (sequence)i(of)g(k)m(eyw)m(ords)g(in)m(to)f(the)h(CHU.)g(The)f (starting)g(index)f(n)m(um)m(b)s(er)227 2619 y(\(nstart\))30 b(m)m(ust)e(b)s(e)g(greater)i(than)f(0.)40 b(One)28 b(ma)m(y)i(app)s (end)d(the)h(same)i(commen)m(t)f(to)h(ev)m(ery)f(k)m(eyw)m(ord)g(\(and) 227 2732 y(eliminate)j(the)i(need)f(to)h(ha)m(v)m(e)g(an)f(arra)m(y)h (of)f(iden)m(tical)g(commen)m(t)h(strings,)f(one)g(for)h(eac)m(h)g(k)m (eyw)m(ord\))g(b)m(y)227 2844 y(including)21 b(the)k(amp)s(ersand)e(c)m (haracter)j(as)e(the)h(last)f(non-blank)f(c)m(haracter)j(in)d(the)h (\(\014rst\))h(COMMENTS)227 2957 y(string)d(parameter.)38 b(This)21 b(same)i(string)e(will)f(then)i(b)s(e)g(used)f(for)h(the)h (commen)m(t)g(\014eld)e(in)g(all)h(the)g(k)m(eyw)m(ords.)227 3070 y(One)32 b(ma)m(y)h(also)f(en)m(ter)g(a)h(n)m(ull)d(p)s(oin)m(ter) h(for)h(the)g(commen)m(t)h(parameter)g(to)f(lea)m(v)m(e)i(the)e(commen) m(t)h(\014eld)e(of)227 3183 y(the)g(k)m(eyw)m(ord)g(blank.)95 3425 y Fe(int)47 b(fits_write_keys_str)c(/)k(ffpkns)286 3537 y(\(fitsfile)f(*fptr,)g(char)g(*keyroot,)g(int)h(nstart,)e(int)i (nkeys,)334 3650 y(char)g(**value,)e(char)i(**comment,)e(>)i(int)g (*status\))95 3876 y(int)g(fits_write_keys_[log,)42 b(lng])47 b(/)g(ffpkn[lj])286 3989 y(\(fitsfile)f(*fptr,)g(char)g(*keyroot,)g (int)h(nstart,)e(int)i(nkeys,)334 4102 y(DTYPE)f(*numval,)g(char)h (**comment,)e(int)i(*status\))95 4328 y(int)g(fits_write_keys_[flt,)42 b(dbl,)47 b(fixflg,)f(fixdbl])g(/)h(ffpkne[edfg])286 4441 y(\(fitsfile)f(*fptr,)g(char)g(*keyroot,)g(int)h(nstart,)e(int)i (nkey,)334 4554 y(DTYPE)f(*numval,)g(int)h(decimals,)e(char)i (**comment,)e(>)i(int)g(*status\))0 4795 y Fi(4)81 b Fj(Cop)m(y)21 b(an)h(indexed)e(k)m(eyw)m(ord)j(from)e(one)h(HDU)h(to)f (another,)i(mo)s(difying)c(the)i(index)e(n)m(um)m(b)s(er)g(of)i(the)g (k)m(eyw)m(ord)227 4908 y(name)37 b(in)e(the)h(pro)s(cess.)58 b(F)-8 b(or)37 b(example,)h(this)d(routine)h(could)f(read)h(the)h (TLMIN3)f(k)m(eyw)m(ord)h(from)f(the)227 5021 y(input)29 b(HDU)i(\(b)m(y)g(giving)f(k)m(eyro)s(ot)h(=)g(`TLMIN')g(and)f(inn)m (um)e(=)i(3\))i(and)e(write)g(it)g(to)h(the)g(output)f(HDU)227 5134 y(with)35 b(the)h(k)m(eyw)m(ord)h(name)f(TLMIN4)g(\(b)m(y)g (setting)h(outn)m(um)e(=)h(4\).)58 b(If)36 b(the)g(input)e(k)m(eyw)m (ord)j(do)s(es)f(not)227 5247 y(exist,)31 b(then)f(this)f(routine)g (simply)f(returns)h(without)h(indicating)e(an)i(error.)95 5488 y Fe(int)47 b(fits_copy_key)e(/)i(ffcpky)286 5601 y(\(fitsfile)f(*infptr,)f(fitsfile)h(*outfptr,)f(int)i(innum,)f(int)h (outnum,)334 5714 y(char)g(*keyroot,)e(>)i(int)g(*status\))p eop %%Page: 90 98 90 97 bop 0 299 a Fj(90)1003 b Fh(CHAPTER)30 b(9.)112 b(SPECIALIZED)28 b(CFITSIO)h(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)0 555 y Fi(5)81 b Fj(W)-8 b(rite)29 b(\(app)s(end\))g(a)h(`triple)d (precision')h(k)m(eyw)m(ord)i(in)m(to)f(the)h(CHU)f(in)f(F28.16)k (format.)41 b(The)29 b(\015oating)g(p)s(oin)m(t)227 668 y(k)m(eyw)m(ord)h(v)-5 b(alue)29 b(is)f(constructed)i(b)m(y)f (concatenating)i(the)e(input)f(in)m(teger)i(v)-5 b(alue)28 b(with)g(the)i(input)d(double)227 781 y(precision)33 b(fraction)g(v)-5 b(alue)34 b(\(whic)m(h)f(m)m(ust)h(ha)m(v)m(e)i(a)e (v)-5 b(alue)34 b(b)s(et)m(w)m(een)g(0.0)i(and)d(1.0\).)53 b(The)34 b(\013gkyt)h(routine)227 894 y(should)c(b)s(e)i(used)f(to)i (read)f(this)f(k)m(eyw)m(ord)i(v)-5 b(alue,)34 b(b)s(ecause)f(the)g (other)h(k)m(eyw)m(ord)f(reading)g(routines)f(will)227 1007 y(not)f(preserv)m(e)f(the)h(full)d(precision)h(of)h(the)h(v)-5 b(alue.)95 1268 y Fe(int)47 b(fits_write_key_triple)42 b(/)48 b(ffpkyt)286 1380 y(\(fitsfile)e(*fptr,)g(char)g(*keyname,)g (long)g(intval,)g(double)g(frac,)334 1493 y(char)h(*comment,)e(>)i(int) g(*status\))0 1754 y Fi(6)81 b Fj(W)-8 b(rite)36 b(k)m(eyw)m(ords)g(to) h(the)f(CHDU)g(that)h(are)f(de\014ned)f(in)g(an)h(ASCI)s(I)e(template)i (\014le.)57 b(The)35 b(format)i(of)f(the)227 1867 y(template)31 b(\014le)f(is)f(describ)s(ed)f(under)h(the)i(\014ts)p 1788 1867 28 4 v 32 w(parse)p 2028 1867 V 33 w(template)f(routine.)95 2128 y Fe(int)47 b(fits_write_key_template)42 b(/)47 b(ffpktp)286 2241 y(\(fitsfile)f(*fptr,)g(const)g(char)h(*filename,)e (>)i(int)g(*status\))0 2532 y Fd(9.3.4)112 b(Insert)38 b(Keyw)m(ord)f(Routines)0 2752 y Fj(These)42 b(insert)g(routines)f(are) i(somewhat)g(less)e(e\016cien)m(t)i(than)g(the)f(`up)s(date')g(or)h (`write')f(k)m(eyw)m(ord)h(routines)0 2864 y(b)s(ecause)30 b(the)g(follo)m(wing)f(k)m(eyw)m(ords)h(in)f(the)h(header)g(m)m(ust)g (b)s(e)f(shifted)g(do)m(wn)g(to)i(mak)m(e)g(ro)s(om)f(for)g(the)g (inserted)0 2977 y(k)m(eyw)m(ord.)41 b(See)31 b(App)s(endix)c(B)k(for)f (the)h(de\014nition)d(of)i(the)h(parameters)g(used)e(in)g(these)i (routines.)0 3238 y Fi(1)81 b Fj(Insert)26 b(a)h(new)f(k)m(eyw)m(ord)h (record)g(in)m(to)f(the)h(CHU)g(at)g(the)g(sp)s(eci\014ed)e(p)s (osition)g(\(i.e.,)j(immediately)d(preceding)227 3351 y(the)31 b(\(k)m(eyn)m(um\)th)g(k)m(eyw)m(ord)g(in)e(the)h(header.\))95 3612 y Fe(int)47 b(fits_insert_record)c(/)48 b(ffirec)286 3725 y(\(fitsfile)e(*fptr,)g(int)h(keynum,)e(char)i(*card,)f(>)i(int)f (*status\))0 3985 y Fi(2)81 b Fj(Insert)24 b(a)h(new)g(k)m(eyw)m(ord)g (in)m(to)g(the)g(CHU.)g(The)g(new)f(k)m(eyw)m(ord)i(is)e(inserted)f (immediately)h(follo)m(wing)f(the)i(last)227 4098 y(k)m(eyw)m(ord)i (that)f(has)f(b)s(een)h(read)f(from)h(the)g(header.)39 b(The)25 b(`longstr')h(v)m(ersion)f(has)g(the)h(same)g(functionalit)m (y)227 4211 y(as)33 b(the)g(`str')f(v)m(ersion)g(except)i(that)f(it)f (also)g(supp)s(orts)f(the)h(lo)s(cal)g(long)g(string)g(k)m(eyw)m(ord)h (con)m(v)m(en)m(tion)g(for)227 4324 y(strings)28 b(longer)g(than)h(68)h (c)m(haracters.)41 b(A)29 b(n)m(ull)e(p)s(oin)m(ter)h(ma)m(y)h(b)s(e)g (en)m(tered)g(for)g(the)g(commen)m(t)g(parameter)227 4437 y(whic)m(h)c(will)d(cause)k(the)g(commen)m(t)h(\014eld)d(to)i(b)s (e)f(left)g(blank.)38 b(The)25 b(\015t,)h(dbl,)f(cmp,)i(and)e(dblcmp)e (v)m(ersions)i(of)227 4550 y(this)k(routine)g(ha)m(v)m(e)i(the)e(added) g(feature)i(that)f(if)f(the)h('decimals')f(parameter)h(is)f(negativ)m (e,)i(then)e(the)h('G')227 4663 y(displa)m(y)e(format)i(rather)f(then)g (the)h('E')f(format)h(will)d(b)s(e)i(used)f(when)h(constructing)g(the)g (k)m(eyw)m(ord)h(v)-5 b(alue,)227 4776 y(taking)26 b(the)h(absolute)f (v)-5 b(alue)25 b(of)i('decimals')e(for)h(the)h(precision.)37 b(This)25 b(will)e(suppress)h(trailing)h(zeros,)j(and)227 4889 y(will)34 b(use)j(a)g(\014xed)f(format)h(rather)g(than)f(an)h(exp) s(onen)m(tial)e(format,)k(dep)s(ending)34 b(on)j(the)g(magnitude)f(of) 227 5002 y(the)31 b(v)-5 b(alue.)95 5262 y Fe(int)47 b(fits_insert_card)d(/)j(ffikey)286 5375 y(\(fitsfile)f(*fptr,)g(char)g (*card,)g(>)i(&status\))95 5601 y(int)f(fits_insert_key_[str,)42 b(longstr])k(/)h(ffi[kys,)f(kls])286 5714 y(\(fitsfile)g(*fptr,)g(char) g(*keyname,)g(char)g(*value,)g(char)h(*comment,)p eop %%Page: 91 99 91 98 bop 0 299 a Fh(9.3.)72 b(SPECIALIZED)29 b(HEADER)i(KEYW)m(ORD)g (R)m(OUTINES)1510 b Fj(91)334 555 y Fe(>)48 b(int)e(*status\))95 781 y(int)h(fits_insert_key_[log,)42 b(lng])47 b(/)g(ffiky[lj])286 894 y(\(fitsfile)f(*fptr,)g(char)g(*keyname,)g(DTYPE)g(numval,)g(char)g (*comment,)334 1007 y(>)i(int)e(*status\))95 1233 y(int)h (fits_insert_key_[flt,)42 b(fixflt,)k(dbl,)h(fixdbl])f(/)h(ffiky[edfg]) 286 1346 y(\(fitsfile)f(*fptr,)g(char)g(*keyname,)g(DTYPE)g(numval,)g (int)h(decimals,)334 1458 y(char)g(*comment,)e(>)i(int)g(*status\))95 1684 y(int)g(fits_insert_key_[cmp,)42 b(dblcmp,)k(fixcmp,)g(fixdblcmp]) f(/)i(ffik[yc,ym,fc,fm])286 1797 y(\(fitsfile)f(*fptr,)g(char)g (*keyname,)g(DTYPE)g(*numval,)g(int)g(decimals,)334 1910 y(char)h(*comment,)e(>)i(int)g(*status\))0 2169 y Fi(3)81 b Fj(Insert)32 b(a)i(new)f(k)m(eyw)m(ord)h(with)e(an)h(unde\014ned,)g (or)g(n)m(ull,)f(v)-5 b(alue)33 b(in)m(to)h(the)f(CHU.)h(The)f(v)-5 b(alue)33 b(string)f(of)i(the)227 2282 y(k)m(eyw)m(ord)d(is)f(left)g (blank)f(in)g(this)g(case.)95 2541 y Fe(int)47 b(fits_insert_key_null)c (/)k(ffikyu)286 2654 y(\(fitsfile)f(*fptr,)g(char)g(*keyname,)g(char)g (*comment,)g(>)h(int)g(*status\))0 2945 y Fd(9.3.5)112 b(Read)38 b(Keyw)m(ord)g(Routines)0 3163 y Fj(Wild)29 b(card)h(c)m(haracters)i(ma)m(y)f(b)s(e)f(used)f(when)h(sp)s(ecifying)e (the)i(name)h(of)f(the)h(k)m(eyw)m(ord)g(to)g(b)s(e)f(read.)0 3422 y Fi(1)81 b Fj(Read)43 b(a)h(k)m(eyw)m(ord)g(v)-5 b(alue)42 b(\(with)h(the)g(appropriate)g(data)h(t)m(yp)s(e\))g(and)e (commen)m(t)j(from)e(the)g(CHU.)h(If)f(a)227 3535 y(NULL)32 b(commen)m(t)h(p)s(oin)m(ter)e(is)h(giv)m(en)g(on)g(input,)e(then)i (the)g(commen)m(t)i(string)d(will)e(not)j(b)s(e)g(returned.)44 b(If)227 3648 y(the)32 b(v)-5 b(alue)32 b(of)g(the)g(k)m(eyw)m(ord)g (is)f(not)i(de\014ned)d(\(i.e.,)j(the)f(v)-5 b(alue)32 b(\014eld)e(is)h(blank\))g(then)h(an)g(error)f(status)h(=)227 3761 y(V)-10 b(ALUE)p 545 3761 28 4 v 33 w(UNDEFINED)29 b(will)c(b)s(e)j(returned)e(and)h(the)h(input)e(v)-5 b(alue)27 b(will)f(not)i(b)s(e)f(c)m(hanged)h(\(except)h(that)227 3874 y(\013gkys)i(will)d(reset)j(the)f(v)-5 b(alue)30 b(to)h(a)g(n)m(ull)d(string\).)95 4133 y Fe(int)47 b(fits_read_key_str) c(/)48 b(ffgkys)286 4246 y(\(fitsfile)e(*fptr,)g(char)g(*keyname,)g(>)h (char)g(*value,)f(char)g(*comment,)334 4359 y(int)h(*status\);)95 4585 y(NOTE:)g(after)f(calling)g(the)h(following)e(routine,)h(programs) f(must)i(explicitly)e(free)382 4698 y(the)i(memory)f(allocated)f(for)i ('longstr')e(after)i(it)g(is)g(no)g(longer)f(needed.)95 4924 y(int)h(fits_read_key_longstr)42 b(/)48 b(ffgkls)286 5036 y(\(fitsfile)e(*fptr,)g(char)g(*keyname,)g(>)h(char)g(**longstr,)e (char)h(*comment,)620 5149 y(int)h(*status\))95 5375 y(int)g(fits_read_key_[log,)c(lng,)k(flt,)f(dbl,)h(cmp,)f(dblcmp])g(/)i (ffgky[ljedcm])286 5488 y(\(fitsfile)e(*fptr,)g(char)g(*keyname,)g(>)h (DTYPE)f(*numval,)g(char)h(*comment,)334 5601 y(int)g(*status\))p eop %%Page: 92 100 92 99 bop 0 299 a Fj(92)1003 b Fh(CHAPTER)30 b(9.)112 b(SPECIALIZED)28 b(CFITSIO)h(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)0 555 y Fi(2)81 b Fj(Read)36 b(a)h(sequence)f(of)h(indexed)d(k)m(eyw)m (ord)j(v)-5 b(alues)36 b(\(e.g.,)j(NAXIS1,)g(NAXIS2,)f(...\).)59 b(The)36 b(input)e(starting)227 668 y(index)j(n)m(um)m(b)s(er)f (\(nstart\))j(m)m(ust)f(b)s(e)f(greater)i(than)e(0.)64 b(If)37 b(the)h(v)-5 b(alue)37 b(of)h(an)m(y)h(of)f(the)g(k)m(eyw)m (ords)g(is)f(not)227 781 y(de\014ned)d(\(i.e.,)i(the)f(v)-5 b(alue)34 b(\014eld)f(is)h(blank\))g(then)g(an)g(error)h(status)g(=)f (V)-10 b(ALUE)p 3009 781 28 4 v 33 w(UNDEFINED)36 b(will)c(b)s(e)227 894 y(returned)21 b(and)h(the)h(input)d(v)-5 b(alue)22 b(for)g(the)g(unde\014ned)e(k)m(eyw)m(ord\(s\))k(will)19 b(not)k(b)s(e)e(c)m(hanged.)39 b(These)22 b(routines)227 1007 y(do)j(not)h(supp)s(ort)d(wild)g(card)i(c)m(haracters)i(in)d(the)i (ro)s(ot)f(name.)39 b(If)25 b(there)h(are)f(no)g(indexed)f(k)m(eyw)m (ords)i(in)e(the)227 1120 y(header)35 b(with)e(the)i(input)d(ro)s(ot)j (name)g(then)f(these)h(routines)f(do)g(not)h(return)e(a)i(non-zero)h (status)e(v)-5 b(alue)227 1233 y(and)30 b(instead)g(simply)e(return)h (nfound)f(=)i(0.)95 1489 y Fe(int)47 b(fits_read_keys_str)c(/)48 b(ffgkns)286 1602 y(\(fitsfile)e(*fptr,)g(char)g(*keyname,)g(int)h (nstart,)e(int)i(nkeys,)334 1715 y(>)h(char)e(**value,)g(int)h (*nfound,)93 b(int)47 b(*status\))95 1941 y(int)g(fits_read_keys_[log,) c(lng,)j(flt,)h(dbl])g(/)g(ffgkn[ljed])286 2054 y(\(fitsfile)f(*fptr,)g (char)g(*keyname,)g(int)h(nstart,)e(int)i(nkeys,)334 2167 y(>)h(DTYPE)e(*numval,)f(int)i(*nfound,)f(int)h(*status\))0 2423 y Fi(3)81 b Fj(Read)37 b(the)h(v)-5 b(alue)37 b(of)h(a)g (\015oating)f(p)s(oin)m(t)g(k)m(eyw)m(ord,)j(returning)c(the)i(in)m (teger)g(and)f(fractional)g(parts)g(of)h(the)227 2536 y(v)-5 b(alue)34 b(in)e(separate)j(routine)e(argumen)m(ts.)52 b(This)32 b(routine)h(ma)m(y)h(b)s(e)f(used)h(to)g(read)g(an)m(y)g(k)m (eyw)m(ord)h(but)e(is)227 2649 y(esp)s(ecially)c(useful)f(for)j (reading)e(the)i('triple)e(precision')f(k)m(eyw)m(ords)j(written)f(b)m (y)g(\013pkyt.)95 2906 y Fe(int)47 b(fits_read_key_triple)c(/)k(ffgkyt) 286 3019 y(\(fitsfile)f(*fptr,)g(char)g(*keyname,)g(>)h(long)g (*intval,)e(double)h(*frac,)334 3132 y(char)h(*comment,)e(int)i (*status\))0 3422 y Fd(9.3.6)112 b(Mo)s(dify)38 b(Keyw)m(ord)f (Routines)0 3641 y Fj(These)31 b(routines)g(mo)s(dify)f(the)i(v)-5 b(alue)31 b(of)h(an)g(existing)e(k)m(eyw)m(ord.)46 b(An)31 b(error)g(is)g(returned)f(if)h(the)h(k)m(eyw)m(ord)g(do)s(es)0 3753 y(not)43 b(exist.)76 b(Wild)41 b(card)i(c)m(haracters)h(ma)m(y)f (b)s(e)f(used)f(when)h(sp)s(ecifying)e(the)j(name)f(of)h(the)f(k)m(eyw) m(ord)h(to)h(b)s(e)0 3866 y(mo)s(di\014ed.)39 b(See)30 b(App)s(endix)e(B)j(for)f(the)g(de\014nition)e(of)j(the)f(parameters)h (used)f(in)f(these)i(routines.)0 4123 y Fi(1)81 b Fj(Mo)s(dify)29 b(\(o)m(v)m(erwrite\))i(the)g(n)m(th)f(80-c)m(haracter)j(header)d (record)h(in)e(the)h(CHU.)95 4380 y Fe(int)47 b(fits_modify_record)c(/) 48 b(ffmrec)286 4492 y(\(fitsfile)e(*fptr,)g(int)h(keynum,)e(char)i (*card,)f(>)i(int)f(*status\))0 4749 y Fi(2)81 b Fj(Mo)s(dify)36 b(\(o)m(v)m(erwrite\))j(the)f(80-c)m(haracter)j(header)c(record)h(for)f (the)h(named)f(k)m(eyw)m(ord)h(in)f(the)h(CHU.)g(This)227 4862 y(can)31 b(b)s(e)f(used)f(to)i(o)m(v)m(erwrite)g(the)g(name)f(of)h (the)f(k)m(eyw)m(ord)h(as)g(w)m(ell)e(as)i(its)f(v)-5 b(alue)29 b(and)h(commen)m(t)i(\014elds.)95 5119 y Fe(int)47 b(fits_modify_card)d(/)j(ffmcrd)286 5231 y(\(fitsfile)f(*fptr,)g(char)g (*keyname,)g(char)g(*card,)g(>)i(int)f(*status\))0 5488 y Fi(5)81 b Fj(Mo)s(dify)29 b(the)h(v)-5 b(alue)30 b(and)f(commen)m(t)i (\014elds)e(of)h(an)g(existing)f(k)m(eyw)m(ord)i(in)e(the)h(CHU.)h(The) e(`longstr')h(v)m(ersion)227 5601 y(has)41 b(the)h(same)f(functionalit) m(y)f(as)h(the)h(`str')f(v)m(ersion)g(except)h(that)g(it)f(also)g(supp) s(orts)e(the)j(lo)s(cal)e(long)227 5714 y(string)28 b(k)m(eyw)m(ord)i (con)m(v)m(en)m(tion)g(for)f(strings)e(longer)i(than)g(68)h(c)m (haracters.)41 b(Optionally)-8 b(,)28 b(one)h(ma)m(y)h(mo)s(dify)p eop %%Page: 93 101 93 100 bop 0 299 a Fh(9.3.)72 b(SPECIALIZED)29 b(HEADER)i(KEYW)m(ORD)g (R)m(OUTINES)1510 b Fj(93)227 555 y(only)27 b(the)h(v)-5 b(alue)27 b(\014eld)g(and)g(lea)m(v)m(e)i(the)f(commen)m(t)h(\014eld)d (unc)m(hanged)i(b)m(y)g(setting)f(the)h(input)e(COMMENT)227 668 y(parameter)d(equal)g(to)g(the)g(amp)s(ersand)e(c)m(haracter)j (\(&\))f(or)g(b)m(y)g(en)m(tering)f(a)h(n)m(ull)e(p)s(oin)m(ter)h(for)g (the)h(commen)m(t)227 781 y(parameter.)40 b(The)24 b(\015t,)i(dbl,)f (cmp,)g(and)g(dblcmp)d(v)m(ersions)j(of)g(this)f(routine)g(ha)m(v)m(e)i (the)f(added)f(feature)h(that)227 894 y(if)g(the)i('decimals')e (parameter)i(is)e(negativ)m(e,)k(then)d(the)g('G')h(displa)m(y)d (format)j(rather)f(then)g(the)g('E')h(format)227 1007 y(will)f(b)s(e)i(used)f(when)h(constructing)g(the)g(k)m(eyw)m(ord)h(v) -5 b(alue,)29 b(taking)f(the)h(absolute)f(v)-5 b(alue)28 b(of)g('decimals')g(for)227 1120 y(the)37 b(precision.)58 b(This)34 b(will)g(suppress)h(trailing)f(zeros,)39 b(and)d(will)e(use)j (a)g(\014xed)e(format)i(rather)g(than)f(an)227 1233 y(exp)s(onen)m (tial)30 b(format,)h(dep)s(ending)c(on)k(the)f(magnitude)g(of)g(the)h (v)-5 b(alue.)95 1468 y Fe(int)47 b(fits_modify_key_[str,)42 b(longstr])k(/)h(ffm[kys,)f(kls])286 1581 y(\(fitsfile)g(*fptr,)g(char) g(*keyname,)g(char)g(*value,)g(char)h(*comment,)334 1694 y(>)h(int)e(*status\);)95 1920 y(int)h(fits_modify_key_[log,)42 b(lng])47 b(/)g(ffmky[lj])286 2032 y(\(fitsfile)f(*fptr,)g(char)g (*keyname,)g(DTYPE)g(numval,)g(char)g(*comment,)334 2145 y(>)i(int)e(*status\))95 2371 y(int)h(fits_modify_key_[flt,)42 b(dbl,)47 b(fixflt,)f(fixdbl])g(/)h(ffmky[edfg])286 2484 y(\(fitsfile)f(*fptr,)g(char)g(*keyname,)g(DTYPE)g(numval,)g(int)h (decimals,)334 2597 y(char)g(*comment,)e(>)i(int)g(*status\))95 2823 y(int)g(fits_modify_key_[cmp,)42 b(dblcmp,)k(fixcmp,)g(fixdblcmp]) f(/)i(ffmk[yc,ym,fc,fm])286 2936 y(\(fitsfile)f(*fptr,)g(char)g (*keyname,)g(DTYPE)g(*numval,)g(int)g(decimals,)334 3049 y(char)h(*comment,)e(>)i(int)g(*status\))0 3284 y Fi(6)81 b Fj(Mo)s(dify)21 b(the)h(v)-5 b(alue)22 b(of)g(an)g(existing)g(k)m (eyw)m(ord)g(to)h(b)s(e)f(unde\014ned,)g(or)g(n)m(ull.)36 b(The)22 b(v)-5 b(alue)21 b(string)h(of)g(the)g(k)m(eyw)m(ord)227 3397 y(is)29 b(set)i(to)g(blank.)39 b(Optionally)-8 b(,)28 b(one)i(ma)m(y)h(lea)m(v)m(e)g(the)g(commen)m(t)g(\014eld)d(unc)m (hanged)i(b)m(y)g(setting)g(the)g(input)227 3510 y(COMMENT)f(parameter) g(equal)f(to)h(the)g(amp)s(ersand)e(c)m(haracter)k(\(&\))e(or)f(b)m(y)h (en)m(tering)f(a)h(n)m(ull)e(p)s(oin)m(ter.)95 3745 y Fe(int)47 b(fits_modify_key_null)c(/)k(ffmkyu)286 3858 y(\(fitsfile)f(*fptr,)g(char)g(*keyname,)g(char)g(*comment,)g(>)h(int)g (*status\))0 4145 y Fd(9.3.7)112 b(Up)s(date)39 b(Keyw)m(ord)e (Routines)0 4350 y Fi(1)81 b Fj(These)29 b(up)s(date)g(routines)g(mo)s (dify)f(the)h(v)-5 b(alue,)30 b(and)f(optionally)f(the)i(commen)m(t)h (\014eld,)e(of)h(the)g(k)m(eyw)m(ord)g(if)e(it)227 4462 y(already)33 b(exists,)g(otherwise)f(the)h(new)f(k)m(eyw)m(ord)h(is)e (app)s(ended)g(to)j(the)f(header.)47 b(A)33 b(separate)g(routine)f(is) 227 4575 y(pro)m(vided)c(for)h(eac)m(h)h(k)m(eyw)m(ord)f(data)h(t)m(yp) s(e.)41 b(The)28 b(`longstr')h(v)m(ersion)g(has)f(the)i(same)f (functionalit)m(y)e(as)j(the)227 4688 y(`str')h(v)m(ersion)f(except)i (that)g(it)e(also)h(supp)s(orts)d(the)j(lo)s(cal)f(long)h(string)e(k)m (eyw)m(ord)j(con)m(v)m(en)m(tion)g(for)e(strings)227 4801 y(longer)h(than)g(68)h(c)m(haracters.)45 b(A)31 b(n)m(ull)e(p)s(oin)m(ter)i(ma)m(y)g(b)s(e)g(en)m(tered)h(for)f(the)g (commen)m(t)i(parameter)e(whic)m(h)227 4914 y(will)f(lea)m(v)m(e)j(the) g(commen)m(t)g(\014eld)e(unc)m(hanged)h(or)g(blank.)45 b(The)31 b(\015t,)i(dbl,)e(cmp,)i(and)e(dblcmp)f(v)m(ersions)i(of)227 5027 y(this)d(routine)g(ha)m(v)m(e)i(the)e(added)g(feature)i(that)f(if) f(the)h('decimals')f(parameter)h(is)f(negativ)m(e,)i(then)e(the)h('G') 227 5140 y(displa)m(y)e(format)i(rather)f(then)g(the)h('E')f(format)h (will)d(b)s(e)i(used)f(when)h(constructing)g(the)g(k)m(eyw)m(ord)h(v)-5 b(alue,)227 5253 y(taking)26 b(the)h(absolute)f(v)-5 b(alue)25 b(of)i('decimals')e(for)h(the)h(precision.)37 b(This)25 b(will)e(suppress)h(trailing)h(zeros,)j(and)227 5366 y(will)34 b(use)j(a)g(\014xed)f(format)h(rather)g(than)f(an)h(exp) s(onen)m(tial)e(format,)k(dep)s(ending)34 b(on)j(the)g(magnitude)f(of) 227 5479 y(the)31 b(v)-5 b(alue.)95 5714 y Fe(int)47 b(fits_update_key_[str,)42 b(longstr])k(/)h(ffu[kys,)f(kls])p eop %%Page: 94 102 94 101 bop 0 299 a Fj(94)1003 b Fh(CHAPTER)30 b(9.)112 b(SPECIALIZED)28 b(CFITSIO)h(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)286 555 y Fe(\(fitsfile)46 b(*fptr,)g(char)g(*keyname,)g(char)g(*value,)g (char)h(*comment,)334 668 y(>)h(int)e(*status\))95 894 y(int)h(fits_update_key_[log,)42 b(lng])47 b(/)g(ffuky[lj])286 1007 y(\(fitsfile)f(*fptr,)g(char)g(*keyname,)g(DTYPE)g(numval,)g(char) g(*comment,)334 1120 y(>)i(int)e(*status\))95 1346 y(int)h (fits_update_key_[flt,)42 b(dbl,)47 b(fixflt,)f(fixdbl])g(/)h (ffuky[edfg])286 1458 y(\(fitsfile)f(*fptr,)g(char)g(*keyname,)g(DTYPE) g(numval,)g(int)h(decimals,)334 1571 y(char)g(*comment,)e(>)i(int)g (*status\))95 1797 y(int)g(fits_update_key_[cmp,)42 b(dblcmp,)k (fixcmp,)g(fixdblcmp])f(/)i(ffuk[yc,ym,fc,fm])286 1910 y(\(fitsfile)f(*fptr,)g(char)g(*keyname,)g(DTYPE)g(*numval,)g(int)g (decimals,)334 2023 y(char)h(*comment,)e(>)i(int)g(*status\))0 2363 y Ff(9.4)135 b(De\014ne)45 b(Data)h(Scaling)g(and)e(Unde\014ned)h (Pixel)h(P)l(arameters)0 2614 y Fj(These)37 b(routines)f(set)i(or)f(mo) s(dify)f(the)h(in)m(ternal)f(parameters)i(used)e(b)m(y)i(CFITSIO)d(to)j (either)f(scale)h(the)f(data)0 2727 y(or)f(to)h(represen)m(t)f (unde\014ned)d(pixels.)56 b(Generally)35 b(CFITSIO)f(will)g(scale)i (the)g(data)h(according)f(to)g(the)h(v)-5 b(alues)0 2840 y(of)35 b(the)f(BSCALE)g(and)g(BZER)m(O)h(\(or)g(TSCALn)d(and)i(TZER)m (On\))g(k)m(eyw)m(ords,)i(ho)m(w)m(ev)m(er)g(these)f(routines)e(ma)m(y) 0 2953 y(b)s(e)f(used)h(to)h(o)m(v)m(erride)f(the)g(k)m(eyw)m(ord)h(v) -5 b(alues.)48 b(This)31 b(ma)m(y)j(b)s(e)f(useful)e(when)h(one)i(w)m (an)m(ts)f(to)h(read)f(or)g(write)g(the)0 3066 y(ra)m(w)f(unscaled)f(v) -5 b(alues)32 b(in)f(the)h(FITS)f(\014le.)46 b(Similarly)-8 b(,)29 b(CFITSIO)i(generally)g(uses)h(the)g(v)-5 b(alue)32 b(of)g(the)h(BLANK)0 3179 y(or)40 b(TNULLn)f(k)m(eyw)m(ord)h(to)h (signify)c(an)j(unde\014ned)e(pixel,)j(but)e(these)h(routines)f(ma)m(y) h(b)s(e)f(used)g(to)i(o)m(v)m(erride)0 3292 y(this)31 b(v)-5 b(alue.)47 b(These)32 b(routines)f(do)i(not)f(create)i(or)f(mo)s (dify)d(the)j(corresp)s(onding)d(header)j(k)m(eyw)m(ord)f(v)-5 b(alues.)47 b(See)0 3405 y(App)s(endix)28 b(B)i(for)h(the)f (de\014nition)e(of)j(the)f(parameters)h(used)e(in)h(these)g(routines.)0 3669 y Fi(1)81 b Fj(Reset)26 b(the)g(scaling)e(factors)i(in)e(the)i (primary)e(arra)m(y)i(or)f(image)h(extension;)h(do)s(es)e(not)g(c)m (hange)i(the)f(BSCALE)227 3782 y(and)i(BZER)m(O)g(k)m(eyw)m(ord)h(v)-5 b(alues)27 b(and)h(only)f(a\013ects)j(the)e(automatic)i(scaling)d(p)s (erformed)g(when)g(the)h(data)227 3895 y(elemen)m(ts)e(are)g (written/read)f(to/from)h(the)g(FITS)f(\014le.)38 b(When)25 b(reading)g(from)g(a)h(FITS)f(\014le)f(the)i(returned)227 4008 y(data)i(v)-5 b(alue)27 b(=)g(\(the)h(v)-5 b(alue)27 b(giv)m(en)h(in)e(the)h(FITS)g(arra)m(y\))h(*)g(BSCALE)f(+)g(BZER)m(O.) g(The)g(in)m(v)m(erse)h(form)m(ula)227 4121 y(is)i(used)f(when)h (writing)e(data)j(v)-5 b(alues)30 b(to)h(the)f(FITS)g(\014le.)95 4386 y Fe(int)47 b(fits_set_bscale)d(/)j(ffpscl)286 4499 y(\(fitsfile)f(*fptr,)g(double)g(scale,)g(double)g(zero,)g(>)i(int)f (*status\))0 4764 y Fi(2)81 b Fj(Reset)39 b(the)f(scaling)g(parameters) g(for)h(a)f(table)g(column;)k(do)s(es)c(not)g(c)m(hange)i(the)e(TSCALn) f(or)h(TZER)m(On)227 4877 y(k)m(eyw)m(ord)29 b(v)-5 b(alues)28 b(and)f(only)h(a\013ects)h(the)g(automatic)g(scaling)e(p)s(erformed)g (when)g(the)i(data)g(elemen)m(ts)g(are)227 4990 y(written/read)i (to/from)h(the)g(FITS)f(\014le.)43 b(When)31 b(reading)f(from)h(a)h (FITS)f(\014le)f(the)i(returned)e(data)i(v)-5 b(alue)227 5103 y(=)25 b(\(the)i(v)-5 b(alue)25 b(giv)m(en)g(in)f(the)i(FITS)f (arra)m(y\))h(*)g(TSCAL)e(+)i(TZER)m(O.)e(The)h(in)m(v)m(erse)h(form)m (ula)f(is)f(used)h(when)227 5216 y(writing)k(data)i(v)-5 b(alues)29 b(to)j(the)e(FITS)g(\014le.)95 5480 y Fe(int)47 b(fits_set_tscale)d(/)j(fftscl)286 5593 y(\(fitsfile)f(*fptr,)g(int)h (colnum,)e(double)i(scale,)f(double)g(zero,)334 5706 y(>)i(int)e(*status\))p eop %%Page: 95 103 95 102 bop 0 299 a Fh(9.5.)72 b(SPECIALIZED)29 b(FITS)g(PRIMAR)-8 b(Y)31 b(ARRA)-8 b(Y)32 b(OR)d(IMA)m(GE)j(EXTENSION)d(I/O)h(R)m (OUTINES)125 b Fj(95)0 555 y Fi(3)81 b Fj(De\014ne)36 b(the)g(in)m(teger)h(v)-5 b(alue)35 b(to)i(b)s(e)e(used)h(to)h(signify) d(unde\014ned)g(pixels)g(in)h(the)h(primary)e(arra)m(y)j(or)f(image)227 668 y(extension.)53 b(This)33 b(is)g(only)h(used)g(if)f(BITPIX)h(=)h (8,)h(16,)g(or)f(32.)54 b(This)33 b(do)s(es)h(not)h(create)h(or)e(c)m (hange)i(the)227 781 y(v)-5 b(alue)30 b(of)h(the)f(BLANK)h(k)m(eyw)m (ord)g(in)e(the)h(header.)95 1038 y Fe(int)47 b(fits_set_imgnull)d(/)j (ffpnul)286 1150 y(\(fitsfile)f(*fptr,)g(long)g(nulval,)g(>)i(int)f (*status\))0 1407 y Fi(4)81 b Fj(De\014ne)36 b(the)g(string)f(to)h(b)s (e)f(used)g(to)i(signify)d(unde\014ned)g(pixels)g(in)g(a)i(column)f(in) g(an)g(ASCI)s(I)g(table.)57 b(This)227 1520 y(do)s(es)30 b(not)h(create)h(or)e(c)m(hange)i(the)e(v)-5 b(alue)30 b(of)h(the)f(TNULLn)g(k)m(eyw)m(ord.)95 1777 y Fe(int)47 b(fits_set_atblnull)c(/)48 b(ffsnul)286 1889 y(\(fitsfile)e(*fptr,)g (int)h(colnum,)e(char)i(*nulstr,)f(>)h(int)g(*status\))0 2146 y Fi(5)81 b Fj(De\014ne)34 b(the)h(v)-5 b(alue)33 b(to)i(b)s(e)f(used)g(to)h(signify)d(unde\014ned)g(pixels)h(in)g(an)h (in)m(teger)h(column)e(in)g(a)h(binary)f(table)227 2259 y(\(where)c(TF)m(ORMn)f(=)g('B',)i('I',)f(or)f('J'\).)i(This)c(do)s(es) j(not)f(create)j(or)d(c)m(hange)i(the)e(v)-5 b(alue)28 b(of)h(the)g(TNULLn)227 2372 y(k)m(eyw)m(ord.)95 2628 y Fe(int)47 b(fits_set_btblnull)c(/)48 b(fftnul)286 2741 y(\(fitsfile)e(*fptr,)g(int)h(colnum,)e(long)i(nulval,)f(>)h(int)g (*status\))0 3074 y Ff(9.5)135 b(Sp)t(ecialized)61 b(FITS)e(Primary)i (Arra)l(y)f(or)h(IMA)l(GE)e(Extension)j(I/O)306 3224 y(Routines)0 3474 y Fj(These)27 b(routines)g(read)g(or)h(write)f(data)h (v)-5 b(alues)27 b(in)g(the)g(primary)f(data)i(arra)m(y)h(\(i.e.,)f (the)g(\014rst)f(HDU)i(in)d(the)i(FITS)0 3587 y(\014le\))36 b(or)h(an)f(IMA)m(GE)h(extension.)59 b(Automatic)38 b(data)f(t)m(yp)s (e)g(con)m(v)m(ersion)f(is)g(p)s(erformed)f(for)h(if)g(the)h(data)g(t)m (yp)s(e)0 3700 y(of)c(the)g(FITS)f(arra)m(y)h(\(as)g(de\014ned)f(b)m(y) g(the)h(BITPIX)g(k)m(eyw)m(ord\))g(di\013ers)f(from)g(the)h(data)g(t)m (yp)s(e)g(of)g(the)g(arra)m(y)g(in)0 3813 y(the)c(calling)f(routine.)39 b(The)28 b(data)i(v)-5 b(alues)28 b(are)i(automatically)f(scaled)f(b)m (y)h(the)h(BSCALE)e(and)g(BZER)m(O)h(header)0 3926 y(v)-5 b(alues)24 b(as)i(they)f(are)g(b)s(eing)f(written)g(or)h(read)f(from)h (the)g(FITS)f(arra)m(y)-8 b(.)40 b(Unlik)m(e)24 b(the)h(basic)g (routines)e(describ)s(ed)g(in)0 4039 y(the)31 b(previous)f(c)m(hapter,) j(most)e(of)h(these)g(routines)e(sp)s(eci\014cally)f(supp)s(ort)g(the)j (FITS)e(random)h(groups)f(format.)0 4152 y(See)h(App)s(endix)c(B)k(for) f(the)h(de\014nition)d(of)i(the)h(parameters)g(used)e(in)g(these)i (routines.)0 4312 y(The)24 b(more)h(primitiv)m(e)e(reading)h(and)g (writing)f(routines)g(\(i.)39 b(e.,)26 b(\013ppr)p 2364 4312 28 4 v 32 w(,)g(\013ppn)p 2653 4312 V 31 w(,)g(\013ppn,)f(\013gp)m (v)p 3185 4312 V 33 w(,)h(or)f(\013gpf)p 3552 4312 V 32 w(\))g(simply)0 4425 y(treat)g(the)g(primary)d(arra)m(y)j(as)f(a)h (long)f(1-dimensional)e(arra)m(y)j(of)f(pixels,)g(ignoring)f(the)h(in)m (trinsic)e(dimensionalit)m(y)0 4538 y(of)30 b(the)g(arra)m(y)-8 b(.)42 b(When)30 b(dealing)f(with)f(a)j(2D)g(image,)f(for)g(example,)g (the)g(application)f(program)h(m)m(ust)g(calculate)0 4650 y(the)i(pixel)e(o\013set)i(in)e(the)i(1-D)h(arra)m(y)f(that)g (corresp)s(onds)e(to)i(an)m(y)g(particular)e(X,)i(Y)f(co)s(ordinate)h (in)e(the)h(image.)0 4763 y(C)25 b(programmers)h(should)e(note)i(that)g (the)h(ordering)d(of)i(arra)m(ys)g(in)f(FITS)g(\014les,)h(and)f(hence)h (in)f(all)f(the)i(CFITSIO)0 4876 y(calls,)38 b(is)e(more)h(similar)e (to)i(the)h(dimensionalit)m(y)c(of)j(arra)m(ys)g(in)f(F)-8 b(ortran)38 b(rather)f(than)f(C.)h(F)-8 b(or)38 b(instance)f(if)f(a)0 4989 y(FITS)28 b(image)h(has)f(NAXIS1)h(=)f(100)i(and)e(NAXIS2)h(=)f (50,)i(then)e(a)h(2-D)h(arra)m(y)f(just)f(large)h(enough)f(to)i(hold)d (the)0 5102 y(image)k(should)d(b)s(e)i(declared)g(as)g(arra)m (y[50][100])k(and)c(not)h(as)f(arra)m(y[100][50].)0 5262 y(F)-8 b(or)36 b(con)m(v)m(enience,)h(higher-lev)m(el)d(routines)g(are) h(also)g(pro)m(vided)f(to)h(sp)s(eci\014cly)e(deal)i(with)f(2D)h (images)g(\(\013p2d)p 3872 5262 V 0 5375 a(and)26 b(\013g2d)p 372 5375 V 33 w(\))h(and)f(3D)i(data)f(cub)s(es)f(\(\013p3d)p 1467 5375 V 59 w(and)g(\013g3d)p 1893 5375 V 33 w(\).)40 b(The)26 b(dimensionalit)m(y)e(of)j(the)g(FITS)f(image)h(is)e(passed)0 5488 y(b)m(y)36 b(the)h(naxis1,)g(naxis2,)h(and)e(naxis3)g(parameters)g (and)g(the)h(declared)e(dimensions)f(of)j(the)f(program)g(arra)m(y)0 5601 y(are)30 b(passed)g(in)e(the)i(dim1)f(and)g(dim2)g(parameters.)41 b(Note)31 b(that)f(the)g(dimensions)d(of)j(the)g(program)g(arra)m(y)g (ma)m(y)0 5714 y(b)s(e)35 b(larger)g(than)g(the)h(dimensions)d(of)j (the)g(FITS)e(arra)m(y)-8 b(.)58 b(F)-8 b(or)36 b(example)f(if)g(a)h (FITS)e(image)i(with)e(NAXIS1)i(=)p eop %%Page: 96 104 96 103 bop 0 299 a Fj(96)1003 b Fh(CHAPTER)30 b(9.)112 b(SPECIALIZED)28 b(CFITSIO)h(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)0 555 y Fj(NAXIS2)36 b(=)g(400)h(is)e(read)h(in)m(to)g(a)h(program)f (arra)m(y)g(whic)m(h)f(is)g(dimensioned)e(as)k(512)g(x)f(512)h(pixels,) f(then)g(the)0 668 y(image)f(will)d(just)i(\014ll)e(the)j(lo)m(w)m(er)g (left)f(corner)g(of)h(the)g(arra)m(y)g(with)e(pixels)g(in)g(the)i (range)g(1)g(-)g(400)g(in)f(the)g(X)h(an)0 781 y(Y)g(directions.)52 b(This)33 b(has)i(the)g(e\013ect)h(of)f(taking)f(a)i(con)m(tiguous)e (set)i(of)f(pixel)e(v)-5 b(alue)34 b(in)f(the)i(FITS)f(arra)m(y)i(and)0 894 y(writing)28 b(them)i(to)h(a)f(non-con)m(tiguous)g(arra)m(y)h(in)d (program)i(memory)g(\(i.e.,)h(there)f(are)h(no)m(w)f(some)g(blank)f (pixels)0 1007 y(around)g(the)i(edge)g(of)g(the)f(image)h(in)e(the)h (program)g(arra)m(y\).)0 1167 y(The)k(most)i(general)e(set)i(of)f (routines)e(\(\013pss)p 1560 1167 28 4 v 33 w(,)j(\013gsv)p 1836 1167 V 33 w(,)g(and)e(\013gsf)p 2273 1167 V 33 w(\))h(ma)m(y)h(b)s (e)e(used)g(to)h(transfer)g(a)g(rectangular)0 1280 y(subset)27 b(of)h(the)g(pixels)d(in)i(a)h(FITS)f(N-dimensional)e(image)j(to)g(or)g (from)f(an)g(arra)m(y)i(whic)m(h)d(has)h(b)s(een)g(declared)g(in)0 1393 y(the)i(calling)e(program.)40 b(The)28 b(fpixel)f(and)h(lpixel)e (parameters)j(are)g(in)m(teger)g(arra)m(ys)g(whic)m(h)e(sp)s(ecify)g (the)i(starting)0 1506 y(and)k(ending)e(pixel)h(co)s(ordinate)h(in)f (eac)m(h)i(dimension)d(\(starting)i(with)f(1,)i(not)g(0\))g(of)f(the)g (FITS)g(image)g(that)h(is)0 1619 y(to)f(b)s(e)e(read)g(or)h(written.)44 b(It)32 b(is)f(imp)s(ortan)m(t)g(to)i(note)f(that)h(these)f(are)g(the)g (starting)g(and)f(ending)f(pixels)g(in)h(the)0 1732 y(FITS)j(image,)j (not)e(in)e(the)i(declared)g(arra)m(y)g(in)e(the)i(program.)54 b(The)35 b(arra)m(y)g(parameter)g(in)f(these)h(routines)f(is)0 1844 y(treated)g(simply)c(as)j(a)f(large)h(one-dimensional)e(arra)m(y)i (of)f(the)h(appropriate)f(data)h(t)m(yp)s(e)g(con)m(taining)f(the)h (pixel)0 1957 y(v)-5 b(alues;)36 b(The)e(pixel)f(v)-5 b(alues)34 b(in)g(the)g(FITS)g(arra)m(y)h(are)g(read/written)f(from/to) i(this)d(program)i(arra)m(y)g(in)e(strict)0 2070 y(sequence)e(without)e (an)m(y)i(gaps;)g(it)f(is)f(up)g(to)j(the)e(calling)f(routine)g(to)j (correctly)e(in)m(terpret)g(the)h(dimensionalit)m(y)0 2183 y(of)d(this)e(arra)m(y)-8 b(.)41 b(The)27 b(t)m(w)m(o)i(FITS)e (reading)g(routines)f(\(\013gsv)p 2018 2183 V 61 w(and)h(\013gsf)p 2415 2183 V 61 w(\))h(also)f(ha)m(v)m(e)i(an)f(`inc')f(parameter)h (whic)m(h)0 2296 y(de\014nes)33 b(the)h(data)h(sampling)d(in)m(terv)-5 b(al)34 b(in)e(eac)m(h)k(dimension)31 b(of)j(the)h(FITS)e(arra)m(y)-8 b(.)53 b(F)-8 b(or)35 b(example,)g(if)e(inc[0]=2)0 2409 y(and)j(inc[1]=3)i(when)e(reading)g(a)h(2-dimensional)e(FITS)h(image,)k (then)c(only)g(ev)m(ery)i(other)f(pixel)f(in)f(the)j(\014rst)0 2522 y(dimension)28 b(and)i(ev)m(ery)h(3rd)f(pixel)e(in)h(the)i(second) f(dimension)e(will)g(b)s(e)i(returned)f(to)i(the)f('arra)m(y')i (parameter.)0 2682 y(Tw)m(o)d(t)m(yp)s(es)h(of)f(routines)f(are)i(pro)m (vided)d(to)j(read)f(the)h(data)g(arra)m(y)f(whic)m(h)f(di\013er)g(in)g (the)i(w)m(a)m(y)g(unde\014ned)d(pixels)0 2795 y(are)38 b(handled.)59 b(The)37 b(\014rst)g(t)m(yp)s(e)g(of)g(routines)g (\(e.g.,)j(\013gp)m(v)p 2059 2795 V 34 w(\))d(simply)e(return)h(an)h (arra)m(y)h(of)g(data)g(elemen)m(ts)f(in)0 2908 y(whic)m(h)29 b(unde\014ned)g(pixels)f(are)j(set)g(equal)f(to)i(a)f(v)-5 b(alue)30 b(sp)s(eci\014ed)e(b)m(y)j(the)g(user)e(in)h(the)g(`n)m(ulv) -5 b(al')30 b(parameter.)41 b(An)0 3021 y(additional)27 b(feature)i(of)g(these)h(routines)d(is)h(that)i(if)e(the)h(user)f(sets) h(n)m(ulv)-5 b(al)27 b(=)i(0,)h(then)e(no)h(c)m(hec)m(ks)h(for)f (unde\014ned)0 3134 y(pixels)23 b(will)f(b)s(e)j(p)s(erformed,)f(th)m (us)h(reducing)e(the)i(amoun)m(t)h(of)f(CPU)f(pro)s(cessing.)38 b(The)24 b(second)h(t)m(yp)s(e)g(of)g(routines)0 3247 y(\(e.g.,)36 b(\013gpf)p 413 3247 V 32 w(\))e(returns)e(the)i(data)g (elemen)m(t)f(arra)m(y)h(and,)g(in)e(addition,)g(a)i(c)m(har)g(arra)m (y)f(that)h(indicates)f(whether)0 3360 y(the)h(v)-5 b(alue)33 b(of)h(the)f(corresp)s(onding)f(data)i(pixel)e(is)h(unde\014ned)e(\(=)j (1\))g(or)g(de\014ned)e(\(=)i(0\).)51 b(The)33 b(latter)h(t)m(yp)s(e)g (of)0 3472 y(routines)c(ma)m(y)i(b)s(e)e(more)i(con)m(v)m(enien)m(t)g (to)g(use)f(in)f(some)h(circumstances,)h(ho)m(w)m(ev)m(er,)h(it)d (requires)g(an)h(additional)0 3585 y(arra)m(y)g(of)f(logical)g(v)-5 b(alues)30 b(whic)m(h)f(can)i(b)s(e)e(un)m(wieldy)f(when)i(w)m(orking)f (with)g(large)i(data)g(arra)m(ys.)0 3859 y Fi(1)81 b Fj(W)-8 b(rite)30 b(elemen)m(ts)h(in)m(to)f(the)h(FITS)f(data)h(arra)m (y)-8 b(.)95 4133 y Fe(int)47 b(fits_write_img)d(/)k(ffppr)286 4246 y(\(fitsfile)e(*fptr,)g(int)h(datatype,)e(long)i(firstelem,)e (long)h(nelements,)334 4359 y(DTYPE)g(*array,)g(int)h(*status\);)95 4585 y(int)g(fits_write_img_[byt,)c(sht,)j(usht,)h(int,)f(uint,)h(lng,) f(ulng,)h(lnglng,)e(flt,)i(dbl])g(/)286 4698 y (ffppr[b,i,ui,k,uk,j,uj,jj,)o(e,d)o(])286 4811 y(\(fitsfile)f(*fptr,)g (long)g(group,)g(long)h(firstelem,)e(long)i(nelements,)334 4924 y(DTYPE)f(*array,)g(>)i(int)f(*status\);)95 5149 y(int)g(fits_write_imgnull)c(/)48 b(ffppn)286 5262 y(\(fitsfile)e (*fptr,)g(int)h(datatype,)e(long)i(firstelem,)e(long)h(nelements,)334 5375 y(DTYPE)g(*array,)g(DTYPE)h(*nulval,)e(>)j(int)f(*status\);)95 5601 y(int)g(fits_write_imgnull_[byt,)42 b(sht,)k(usht,)h(int,)f(uint,) h(lng,)f(ulng,)h(lnglng,)e(flt,)i(dbl])g(/)286 5714 y (ffppn[b,i,ui,k,uk,j,uj,jj,)o(e,d)o(])p eop %%Page: 97 105 97 104 bop 0 299 a Fh(9.5.)72 b(SPECIALIZED)29 b(FITS)g(PRIMAR)-8 b(Y)31 b(ARRA)-8 b(Y)32 b(OR)d(IMA)m(GE)j(EXTENSION)d(I/O)h(R)m (OUTINES)125 b Fj(97)286 555 y Fe(\(fitsfile)46 b(*fptr,)g(long)g (group,)g(long)h(firstelem,)525 668 y(long)g(nelements,)e(DTYPE)h (*array,)g(DTYPE)g(nulval,)g(>)h(int)g(*status\);)0 924 y Fi(2)81 b Fj(Set)30 b(data)h(arra)m(y)g(elemen)m(ts)g(as)f (unde\014ned.)95 1180 y Fe(int)47 b(fits_write_img_null)c(/)k(ffppru) 286 1293 y(\(fitsfile)f(*fptr,)g(long)g(group,)g(long)h(firstelem,)e (long)i(nelements,)334 1406 y(>)h(int)e(*status\))0 1662 y Fi(3)81 b Fj(W)-8 b(rite)31 b(v)-5 b(alues)29 b(in)m(to)i(group)f (parameters.)42 b(This)29 b(routine)g(only)h(applies)f(to)i(the)g (`Random)f(Group)s(ed')g(FITS)227 1775 y(format)22 b(whic)m(h)e(has)h (b)s(een)f(used)h(for)g(applications)e(in)h(radio)h(in)m(terferometry) -8 b(,)24 b(but)c(is)g(o\016cially)g(deprecated)227 1888 y(for)30 b(future)g(use.)95 2144 y Fe(int)47 b(fits_write_grppar_[byt,) 42 b(sht,)k(usht,)h(int,)f(uint,)h(lng,)f(ulng,)h(lnglng,)f(flt,)g (dbl])h(/)286 2257 y(ffpgp[b,i,ui,k,uk,j,uj,jj,)o(e,d)o(])286 2370 y(\(fitsfile)f(*fptr,)g(long)g(group,)g(long)h(firstelem,)e(long)i (nelements,)334 2483 y(>)h(DTYPE)e(*array,)g(int)h(*status\))0 2739 y Fi(4)81 b Fj(W)-8 b(rite)30 b(a)h(2-D)h(or)e(3-D)h(image)g(in)m (to)f(the)h(data)g(arra)m(y)-8 b(.)95 2996 y Fe(int)47 b(fits_write_2d_[byt,)c(sht,)k(usht,)f(int,)h(uint,)f(lng,)h(ulng,)f (lnglng,)g(flt,)g(dbl])h(/)286 3108 y(ffp2d[b,i,ui,k,uk,j,uj,jj,)o(e,d) o(])286 3221 y(\(fitsfile)f(*fptr,)g(long)g(group,)g(long)h(dim1,)f (long)h(naxis1,)334 3334 y(long)g(naxis2,)f(DTYPE)g(*array,)g(>)h(int)g (*status\))95 3560 y(int)g(fits_write_3d_[byt,)c(sht,)k(usht,)f(int,)h (uint,)f(lng,)h(ulng,)f(lnglng,)g(flt,)g(dbl])h(/)286 3673 y(ffp3d[b,i,ui,k,uk,j,uj,jj,)o(e,d)o(])286 3786 y(\(fitsfile)f(*fptr,)g(long)g(group,)g(long)h(dim1,)f(long)h(dim2,)334 3899 y(long)g(naxis1,)f(long)g(naxis2,)g(long)h(naxis3,)e(DTYPE)i (*array,)f(>)h(int)g(*status\))0 4155 y Fi(5)81 b Fj(W)-8 b(rite)30 b(an)h(arbitrary)e(data)i(subsection)e(in)m(to)i(the)f(data)h (arra)m(y)-8 b(.)95 4411 y Fe(int)47 b(fits_write_subset_[byt,)42 b(sht,)k(usht,)h(int,)f(uint,)h(lng,)f(ulng,)h(lnglng,)f(flt,)g(dbl])h (/)286 4524 y(ffpss[b,i,ui,k,uk,j,uj,jj,)o(e,d)o(])286 4637 y(\(fitsfile)f(*fptr,)g(long)g(group,)g(long)h(naxis,)f(long)h (*naxes,)334 4750 y(long)g(*fpixel,)e(long)i(*lpixel,)e(DTYPE)i (*array,)f(>)h(int)g(*status\))0 5006 y Fi(6)81 b Fj(Read)30 b(elemen)m(ts)h(from)f(the)g(FITS)g(data)h(arra)m(y)-8 b(.)95 5262 y Fe(int)47 b(fits_read_img)e(/)i(ffgpv)286 5375 y(\(fitsfile)f(*fptr,)g(int)94 b(datatype,)46 b(long)g(firstelem,) f(long)i(nelements,)334 5488 y(DTYPE)f(*nulval,)g(>)h(DTYPE)g(*array,)f (int)h(*anynul,)e(int)i(*status\))95 5714 y(int)g(fits_read_img_[byt,)c (sht,)k(usht,)f(int,)h(uint,)f(lng,)h(ulng,)f(lnglng,)g(flt,)g(dbl])h (/)p eop %%Page: 98 106 98 105 bop 0 299 a Fj(98)1003 b Fh(CHAPTER)30 b(9.)112 b(SPECIALIZED)28 b(CFITSIO)h(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)286 555 y Fe(ffgpv[b,i,ui,k,uk,j,uj,jj,)o(e,d)o(])286 668 y(\(fitsfile)46 b(*fptr,)g(long)g(group,)g(long)h(firstelem,)e(long)i (nelements,)334 781 y(DTYPE)f(nulval,)g(>)i(DTYPE)e(*array,)g(int)h (*anynul,)e(int)i(*status\))95 1007 y(int)g(fits_read_imgnull)c(/)48 b(ffgpf)286 1120 y(\(fitsfile)e(*fptr,)g(int)94 b(datatype,)46 b(long)g(firstelem,)f(long)i(nelements,)334 1233 y(>)h(DTYPE)e(*array,) g(char)g(*nullarray,)f(int)i(*anynul,)f(int)g(*status\))95 1458 y(int)95 b(fits_read_imgnull_[byt,)42 b(sht,)k(usht,)h(int,)f (uint,)h(lng,)f(ulng,)h(flt,)f(dbl])h(/)334 1571 y (ffgpf[b,i,ui,k,uk,j,uj,jj)o(,e,)o(d])334 1684 y(\(fitsfile)e(*fptr,)h (long)h(group,)f(long)h(firstelem,)e(long)h(nelements,)334 1797 y(>)i(DTYPE)e(*array,)g(char)g(*nullarray,)f(int)i(*anynul,)f(int) g(*status\))0 2055 y Fi(7)81 b Fj(Read)29 b(v)-5 b(alues)30 b(from)f(group)g(parameters.)41 b(This)28 b(routine)g(only)h(applies)f (to)j(the)e(`Random)h(Group)s(ed')f(FITS)227 2168 y(format)22 b(whic)m(h)e(has)h(b)s(een)f(used)h(for)g(applications)e(in)h(radio)h (in)m(terferometry)-8 b(,)24 b(but)c(is)g(o\016cially)g(deprecated)227 2281 y(for)30 b(future)g(use.)95 2538 y Fe(int)95 b (fits_read_grppar_[byt,)42 b(sht,)k(usht,)h(int,)f(uint,)h(lng,)f (ulng,)h(lnglng,)f(flt,)g(dbl])h(/)334 2651 y (ffggp[b,i,ui,k,uk,j,uj,jj)o(,e,)o(d])334 2764 y(\(fitsfile)e(*fptr,)h (long)h(group,)f(long)h(firstelem,)e(long)h(nelements,)334 2877 y(>)i(DTYPE)e(*array,)g(int)h(*status\))0 3135 y Fi(8)81 b Fj(Read)37 b(2-D)h(or)g(3-D)g(image)f(from)g(the)g(data)h (arra)m(y)-8 b(.)62 b(Unde\014ned)36 b(pixels)g(in)f(the)j(arra)m(y)g (will)c(b)s(e)j(set)g(equal)227 3247 y(to)32 b(the)g(v)-5 b(alue)30 b(of)i('n)m(ulv)-5 b(al',)30 b(unless)g(n)m(ulv)-5 b(al=0)29 b(in)h(whic)m(h)g(case)i(no)f(testing)h(for)f(unde\014ned)e (pixels)g(will)g(b)s(e)227 3360 y(p)s(erformed.)95 3618 y Fe(int)95 b(fits_read_2d_[byt,)43 b(sht,)k(usht,)f(int,)h(uint,)f (lng,)h(ulng,)f(lnglng,)g(flt,)g(dbl])h(/)334 3731 y (ffg2d[b,i,ui,k,uk,j,uj,jj)o(,e,)o(d])334 3844 y(\(fitsfile)e(*fptr,)h (long)h(group,)f(DTYPE)h(nulval,)e(long)i(dim1,)f(long)h(naxis1,)334 3957 y(long)g(naxis2,)f(>)h(DTYPE)f(*array,)g(int)h(*anynul,)f(int)h (*status\))95 4183 y(int)95 b(fits_read_3d_[byt,)43 b(sht,)k(usht,)f (int,)h(uint,)f(lng,)h(ulng,)f(lnglng,)g(flt,)g(dbl])h(/)334 4295 y(ffg3d[b,i,ui,k,uk,j,uj,jj)o(,e,)o(d])334 4408 y(\(fitsfile)e(*fptr,)h(long)h(group,)f(DTYPE)h(nulval,)e(long)i(dim1,) 334 4521 y(long)g(dim2,)f(long)h(naxis1,)f(long)g(naxis2,)g(long)h (naxis3,)334 4634 y(>)h(DTYPE)e(*array,)g(int)h(*anynul,)e(int)i (*status\))0 4892 y Fi(9)81 b Fj(Read)30 b(an)g(arbitrary)g(data)h (subsection)e(from)h(the)g(data)i(arra)m(y)-8 b(.)95 5149 y Fe(int)95 b(fits_read_subset_[byt,)42 b(sht,)k(usht,)h(int,)f (uint,)h(lng,)f(ulng,)h(lnglng,)f(flt,)g(dbl])h(/)334 5262 y(ffgsv[b,i,ui,k,uk,j,uj,jj)o(,e,)o(d])334 5375 y(\(fitsfile)e(*fptr,)h(int)h(group,)f(int)h(naxis,)f(long)h(*naxes,) 334 5488 y(long)g(*fpixel,)e(long)i(*lpixel,)e(long)i(*inc,)f(DTYPE)h (nulval,)334 5601 y(>)h(DTYPE)e(*array,)g(int)h(*anynul,)e(int)i (*status\))p eop %%Page: 99 107 99 106 bop 0 299 a Fh(9.6.)72 b(SPECIALIZED)29 b(FITS)g(ASCI)s(I)g(AND) i(BINAR)-8 b(Y)32 b(T)-8 b(ABLE)30 b(R)m(OUTINES)978 b Fj(99)95 555 y Fe(int)95 b(fits_read_subsetnull_[byt)o(,)42 b(sht,)k(usht,)h(int,)f(uint,)h(lng,)f(ulng,)h(lnglng,)f(flt,)g(dbl])h (/)334 668 y(ffgsf[b,i,ui,k,uk,j,uj,jj)o(,e,)o(d])334 781 y(\(fitsfile)e(*fptr,)h(int)h(group,)f(int)h(naxis,)f(long)h (*naxes,)334 894 y(long)g(*fpixel,)e(long)i(*lpixel,)e(long)i(*inc,)f (>)i(DTYPE)e(*array,)334 1007 y(char)h(*nullarray,)d(int)j(*anynul,)f (int)h(*status\))0 1338 y Ff(9.6)135 b(Sp)t(ecialized)46 b(FITS)e(ASCI)t(I)g(and)g(Binary)h(T)-11 b(able)45 b(Routines)0 1591 y Fd(9.6.1)112 b(General)38 b(Column)e(Routines)0 1797 y Fi(1)81 b Fj(Get)31 b(information)d(ab)s(out)i(an)g(existing)f (ASCI)s(I)f(or)i(binary)e(table)i(column.)40 b(A)30 b(n)m(ull)e(p)s (oin)m(ter)h(ma)m(y)i(b)s(e)e(giv)m(en)227 1910 y(for)40 b(an)m(y)h(of)f(the)h(output)f(parameters)g(that)h(are)g(not)f(needed.) 70 b(D)m(A)-8 b(T)g(A)g(TYPE)42 b(is)d(a)i(c)m(haracter)h(string)227 2023 y(whic)m(h)c(returns)f(the)i(data)g(t)m(yp)s(e)g(of)g(the)f (column)g(as)h(de\014ned)e(b)m(y)i(the)f(TF)m(ORMn)h(k)m(eyw)m(ord)g (\(e.g.,)j('I',)227 2136 y('J','E',)28 b('D',)g(etc.\).)41 b(In)27 b(the)g(case)g(of)g(an)g(ASCI)s(I)f(c)m(haracter)i(column,)f(t) m(yp)s(eco)s(de)g(will)d(ha)m(v)m(e)k(a)f(v)-5 b(alue)27 b(of)g(the)227 2249 y(form)g('An')g(where)f('n')h(is)f(an)h(in)m(teger) h(expressing)d(the)i(width)f(of)h(the)g(\014eld)f(in)f(c)m(haracters.) 41 b(F)-8 b(or)28 b(example,)227 2362 y(if)f(TF)m(ORM)i(=)e('160A8')k (then)d(\013gb)s(cl)f(will)e(return)i(t)m(yp)s(ec)m(har='A8')j(and)d (rep)s(eat=20.)41 b(All)27 b(the)h(returned)227 2475 y(parameters)j(are)g(scalar)f(quan)m(tities.)95 2716 y Fe(int)47 b(fits_get_acolparms)c(/)48 b(ffgacl)191 2829 y(\(fitsfile)d(*fptr,)h(int)h(colnum,)f(>)h(char)g(*ttype,)f(long) h(*tbcol,)239 2942 y(char)f(*tunit,)g(char)h(*tform,)f(double)g (*scale,)f(double)i(*zero,)239 3055 y(char)f(*nulstr,)g(char)g(*tdisp,) g(int)h(*status\))95 3280 y(int)g(fits_get_bcolparms)c(/)48 b(ffgbcl)286 3393 y(\(fitsfile)e(*fptr,)g(int)h(colnum,)e(>)j(char)f (*ttype,)e(char)i(*tunit,)334 3506 y(char)g(*typechar,)e(long)h (*repeat,)g(double)g(*scale,)g(double)g(*zero,)334 3619 y(long)h(*nulval,)e(char)i(*tdisp,)f(int)94 b(*status\))0 3861 y Fi(2)81 b Fj(Return)27 b(optimal)g(n)m(um)m(b)s(er)g(of)h(ro)m (ws)g(to)h(read)f(or)g(write)f(at)i(one)f(time)g(for)g(maxim)m(um)f (I/O)g(e\016ciency)-8 b(.)41 b(Refer)227 3973 y(to)25 b(the)g(\\Optimizing)d(Co)s(de")i(section)h(in)e(Chapter)h(5)g(for)g (more)h(discussion)d(on)i(ho)m(w)g(to)h(use)f(this)g(routine.)95 4328 y Fe(int)47 b(fits_get_rowsize)d(/)j(ffgrsz)286 4441 y(\(fitsfile)f(*fptr,)g(long)g(*nrows,)g(*status\))0 4682 y Fi(3)81 b Fj(De\014ne)22 b(the)g(zero)i(indexed)c(b)m(yte)j (o\013set)g(of)g(the)f('heap')h(measured)e(from)h(the)h(start)g(of)f (the)g(binary)f(table)h(data.)227 4795 y(By)30 b(default)f(the)g(heap)h (is)e(assumed)h(to)h(start)g(immediately)e(follo)m(wing)g(the)i (regular)e(table)i(data,)g(i.e.,)g(at)227 4908 y(lo)s(cation)36 b(NAXIS1)h(x)g(NAXIS2.)59 b(This)35 b(routine)g(is)h(only)f(relev)-5 b(an)m(t)37 b(for)f(binary)f(tables)h(whic)m(h)g(con)m(tain)227 5021 y(v)-5 b(ariable)23 b(length)h(arra)m(y)h(columns)e(\(with)g(TF)m (ORMn)h(=)g('Pt'\).)40 b(This)22 b(routine)i(also)g(automatically)g (writes)227 5134 y(the)35 b(v)-5 b(alue)34 b(of)h(theap)f(to)h(a)g(k)m (eyw)m(ord)g(in)f(the)g(extension)g(header.)53 b(This)33 b(routine)g(m)m(ust)i(b)s(e)f(called)f(after)227 5247 y(the)e(required)d(k)m(eyw)m(ords)i(ha)m(v)m(e)i(b)s(een)d(written)g (\(with)g(\013ph)m(bn\))g(but)h(b)s(efore)f(an)m(y)i(data)g(is)e (written)g(to)i(the)227 5360 y(table.)95 5601 y Fe(int)47 b(fits_write_theap)d(/)j(ffpthp)286 5714 y(\(fitsfile)f(*fptr,)g(long)g (theap,)g(>)i(int)f(*status\))p eop %%Page: 100 108 100 107 bop 0 299 a Fj(100)958 b Fh(CHAPTER)30 b(9.)112 b(SPECIALIZED)28 b(CFITSIO)h(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)0 555 y Fi(4)81 b Fj(T)-8 b(est)37 b(the)f(con)m(ten)m(ts)i(of)f(the)g (binary)d(table)j(v)-5 b(ariable)35 b(arra)m(y)i(heap,)h(returning)d (the)h(size)g(of)h(the)g(heap,)h(the)227 668 y(n)m(um)m(b)s(er)30 b(of)h(un)m(used)e(b)m(ytes)j(that)f(are)g(not)g(curren)m(tly)f(p)s (oin)m(ted)g(to)i(b)m(y)e(an)m(y)i(of)f(the)g(descriptors,)f(and)g(the) 227 781 y(n)m(um)m(b)s(er)d(of)h(b)m(ytes)h(whic)m(h)e(are)h(p)s(oin)m (ted)f(to)i(b)m(y)f(m)m(ultiple)e(descriptors.)39 b(It)28 b(also)g(returns)f(v)-5 b(alid)27 b(=)g(F)-10 b(ALSE)227 894 y(if)30 b(an)m(y)g(of)h(the)f(descriptors)g(p)s(oin)m(t)f(to)i(in)m (v)-5 b(alid)28 b(addresses)i(out)g(of)h(range)g(of)f(the)h(heap.)95 1153 y Fe(int)47 b(fits_test_heap)d(/)k(fftheap)286 1266 y(\(fitsfile)e(*fptr,)g(>)h(long)g(*heapsize,)e(long)h(*unused,)g(long) h(*overlap,)334 1379 y(int)g(*validheap,)e(int)i(*status\))0 1637 y Fi(5)81 b Fj(Re-pac)m(k)33 b(the)f(v)m(ectors)h(in)d(the)i (binary)e(table)i(v)-5 b(ariable)30 b(arra)m(y)i(heap)g(to)g(reco)m(v)m (er)i(an)m(y)e(un)m(used)e(space.)45 b(Nor-)227 1750 y(mally)-8 b(,)38 b(when)f(a)g(v)m(ector)i(in)d(a)h(v)-5 b(ariable)36 b(length)h(arra)m(y)g(column)f(is)g(rewritten)h(the)g (previously)e(written)227 1863 y(arra)m(y)f(remains)d(in)h(the)h(heap)f (as)h(w)m(asted)h(un)m(used)d(space.)49 b(This)31 b(routine)g(will)g (repac)m(k)i(the)g(arra)m(ys)g(that)227 1976 y(are)h(still)d(in)h(use,) i(th)m(us)f(eliminating)d(an)m(y)k(b)m(ytes)g(in)e(the)h(heap)g(that)h (are)g(no)f(longer)g(in)f(use.)49 b(Note)34 b(that)227 2089 y(if)e(sev)m(eral)h(v)m(ectors)h(p)s(oin)m(t)d(to)j(the)e(same)h (b)m(ytes)g(in)f(the)g(heap,)i(then)e(this)f(routine)h(will)e(mak)m(e)j (duplicate)227 2202 y(copies)d(of)h(the)g(b)m(ytes)f(for)h(eac)m(h)g(v) m(ector,)h(whic)m(h)d(will)f(actually)i(expand)g(the)g(size)h(of)f(the) h(heap.)95 2461 y Fe(int)47 b(fits_compress_heap)c(/)48 b(ffcmph)286 2574 y(\(fitsfile)e(*fptr,)g(>)h(int)g(*status\))0 2864 y Fd(9.6.2)112 b(Lo)m(w-Lev)m(el)38 b(T)-9 b(able)37 b(Access)g(Routines)0 3083 y Fj(The)g(follo)m(wing)g(2)h(routines)e (pro)m(vide)h(lo)m(w-lev)m(el)h(access)h(to)g(the)f(data)g(in)f(ASCI)s (I)f(or)i(binary)e(tables)h(and)h(are)0 3196 y(mainly)27 b(useful)g(as)j(an)f(e\016cien)m(t)g(w)m(a)m(y)h(to)g(cop)m(y)g(all)e (or)h(part)g(of)g(a)g(table)g(from)g(one)g(lo)s(cation)g(to)h(another.) 40 b(These)0 3309 y(routines)23 b(simply)f(read)i(or)h(write)e(the)i (sp)s(eci\014ed)d(n)m(um)m(b)s(er)h(of)i(consecutiv)m(e)g(b)m(ytes)g (in)e(an)h(ASCI)s(I)f(or)h(binary)f(table,)0 3422 y(without)g(regard)h (for)f(column)g(b)s(oundaries)e(or)j(the)g(ro)m(w)g(length)f(in)f(the)i (table.)39 b(These)23 b(routines)g(do)g(not)h(p)s(erform)0 3535 y(an)m(y)36 b(mac)m(hine)g(dep)s(enden)m(t)f(data)i(con)m(v)m (ersion)f(or)h(b)m(yte)f(sw)m(apping.)57 b(See)36 b(App)s(endix)d(B)k (for)f(the)g(de\014nition)e(of)0 3648 y(the)d(parameters)f(used)g(in)f (these)i(routines.)0 3906 y Fi(1)81 b Fj(Read)30 b(or)h(write)e(a)i (consecutiv)m(e)g(arra)m(y)g(of)g(b)m(ytes)f(from)g(an)h(ASCI)s(I)d(or) j(binary)d(table)95 4165 y Fe(int)47 b(fits_read_tblbytes)c(/)48 b(ffgtbb)286 4278 y(\(fitsfile)e(*fptr,)g(long)g(firstrow,)g(long)g (firstchar,)f(long)i(nchars,)334 4391 y(>)h(unsigned)d(char)i(*values,) e(int)i(*status\))95 4617 y(int)g(fits_write_tblbytes)c(/)k(ffptbb)286 4730 y(\(fitsfile)f(*fptr,)g(long)g(firstrow,)g(long)g(firstchar,)f (long)i(nchars,)334 4843 y(unsigned)f(char)g(*values,)g(>)h(int)g (*status\))0 5133 y Fd(9.6.3)112 b(W)-9 b(rite)36 b(Column)g(Data)i (Routines)0 5342 y Fi(1)81 b Fj(W)-8 b(rite)27 b(elemen)m(ts)h(in)m(to) f(an)h(ASCI)s(I)d(or)j(binary)d(table)j(column)e(\(in)g(the)i(CDU\).)g (The)f(data)h(t)m(yp)s(e)f(of)h(the)f(arra)m(y)227 5455 y(is)j(implied)d(b)m(y)j(the)h(su\016x)e(of)i(the)f(routine)g(name.)95 5714 y Fe(int)47 b(fits_write_col_str)c(/)48 b(ffpcls)p eop %%Page: 101 109 101 108 bop 0 299 a Fh(9.6.)72 b(SPECIALIZED)29 b(FITS)g(ASCI)s(I)g (AND)i(BINAR)-8 b(Y)32 b(T)-8 b(ABLE)30 b(R)m(OUTINES)933 b Fj(101)286 555 y Fe(\(fitsfile)46 b(*fptr,)g(int)h(colnum,)e(long)i (firstrow,)e(long)i(firstelem,)334 668 y(long)g(nelements,)e(char)h (**array,)g(>)h(int)g(*status\))95 894 y(int)g (fits_write_col_[log,byt,sh)o(t,u)o(sht,)o(int,)o(uin)o(t,ln)o(g,ul)o (ng,)o(lngl)o(ng,f)o(lt,)o(dbl,)o(cmp,)o(dbl)o(cmp])41 b(/)286 1007 y(ffpcl[l,b,i,ui,k,uk,j,uj,j)o(j,e)o(,d,c)o(,m])286 1120 y(\(fitsfile)46 b(*fptr,)g(int)h(colnum,)e(long)i(firstrow,)525 1233 y(long)g(firstelem,)e(long)h(nelements,)f(DTYPE)i(*array,)e(>)j (int)f(*status\))0 1487 y Fi(2)81 b Fj(W)-8 b(rite)35 b(elemen)m(ts)h(in)m(to)g(an)f(ASCI)s(I)f(or)i(binary)d(table)j(column) e(substituting)f(the)j(appropriate)e(FITS)h(n)m(ull)227 1600 y(v)-5 b(alue)37 b(for)h(an)m(y)g(elemen)m(ts)g(that)g(are)g (equal)f(to)i(the)f(n)m(ulv)-5 b(al)36 b(parameter.)63 b(This)36 b(routines)g(m)m(ust)i(not)g(b)s(e)227 1713 y(used)30 b(to)h(write)f(to)h(v)-5 b(ariable)29 b(length)h(arra)m(y)g (columns.)95 1967 y Fe(int)47 b(fits_write_colnull_[log,)42 b(byt,)k(sht,)h(usht,)f(int,)h(uint,)f(lng,)h(ulng,)f(lnglng,)g(flt,)h (dbl])f(/)286 2080 y(ffpcn[l,b,i,ui,k,uk,j,uj,j)o(j,e)o(,d])286 2193 y(\(fitsfile)g(*fptr,)g(int)h(colnum,)e(long)i(firstrow,)e(long)i (firstelem,)334 2306 y(long)g(nelements,)e(DTYPE)h(*array,)g(DTYPE)g (nulval,)g(>)i(int)e(*status\))0 2560 y Fi(3)81 b Fj(W)-8 b(rite)26 b(string)g(elemen)m(ts)h(in)m(to)f(a)h(binary)e(table)h (column)f(\(in)h(the)g(CDU\))i(substituting)c(the)i(FITS)g(n)m(ull)e(v) -5 b(alue)227 2673 y(for)28 b(an)m(y)f(elemen)m(ts)h(that)g(are)g (equal)f(to)i(the)e(n)m(ulstr)f(string.)39 b(This)26 b(routine)g(m)m(ust)i(NOT)f(b)s(e)g(used)f(to)j(write)227 2786 y(to)i(v)-5 b(ariable)30 b(length)f(arra)m(y)i(columns.)95 3040 y Fe(int)47 b(fits_write_colnull_str)42 b(/)48 b(ffpcns)286 3153 y(\(fitsfile)e(*fptr,)g(int)h(colnum,)e(long)i(firstrow,)e(long)i (firstelem,)334 3266 y(long)g(nelements,)e(char)h(**array,)g(char)h (*nulstr,)e(>)j(int)e(*status\))0 3520 y Fi(4)81 b Fj(W)-8 b(rite)33 b(bit)f(v)-5 b(alues)32 b(in)m(to)h(a)h(binary)d(b)m(yte)i (\('B'\))i(or)e(bit)f(\('X'\))i(table)f(column)f(\(in)g(the)h(CDU\).)h (Larra)m(y)f(is)f(an)227 3633 y(arra)m(y)25 b(of)g(c)m(haracters)h (corresp)s(onding)d(to)i(the)g(sequence)g(of)f(bits)g(to)h(b)s(e)f (written.)38 b(If)24 b(an)g(elemen)m(t)h(of)g(larra)m(y)227 3746 y(is)j(true)h(\(not)h(equal)e(to)i(zero\))g(then)f(the)g(corresp)s (onding)e(bit)h(in)g(the)h(FITS)f(table)h(is)f(set)i(to)g(1,)g (otherwise)227 3859 y(the)37 b(bit)f(is)g(set)h(to)g(0.)60 b(The)37 b('X')g(column)e(in)h(a)h(FITS)f(table)g(is)g(alw)m(a)m(ys)h (padded)f(out)h(to)g(a)g(m)m(ultiple)e(of)227 3972 y(8)i(bits)e(where)h (the)g(bit)g(arra)m(y)g(starts)h(with)e(the)i(most)f(signi\014can)m(t)f (bit)h(of)g(the)h(b)m(yte)g(and)e(w)m(orks)h(do)m(wn)227 4085 y(to)m(w)m(ards)h(the)g(1's)f(bit.)58 b(F)-8 b(or)37 b(example,)h(a)e('4X')h(arra)m(y)-8 b(,)39 b(with)c(the)i(\014rst)e (bit)h(=)f(1)i(and)f(the)g(remaining)f(3)227 4197 y(bits)30 b(=)h(0)h(is)e(equiv)-5 b(alen)m(t)31 b(to)h(the)g(8-bit)f(unsigned)e (b)m(yte)j(decimal)e(v)-5 b(alue)31 b(of)h(128)g(\('1000)i(0000B'\).)g (In)d(the)227 4310 y(case)h(of)f('X')g(columns,)f(CFITSIO)g(can)h (write)f(to)h(all)f(8)h(bits)f(of)h(eac)m(h)h(b)m(yte)f(whether)f(they) h(are)g(formally)227 4423 y(v)-5 b(alid)32 b(or)h(not.)50 b(Th)m(us)32 b(if)h(the)g(column)f(is)h(de\014ned)f(as)h('4X',)i(and)e (one)g(calls)g(\013p)s(clx)f(with)g(\014rstbit=1)g(and)227 4536 y(n)m(bits=8,)i(then)g(all)e(8)j(bits)d(will)f(b)s(e)j(written)f (in)m(to)g(the)h(\014rst)f(b)m(yte)i(\(as)f(opp)s(osed)f(to)i(writing)c (the)j(\014rst)g(4)227 4649 y(bits)27 b(in)m(to)h(the)f(\014rst)g(ro)m (w)h(and)f(then)h(the)g(next)g(4)g(bits)e(in)m(to)i(the)g(next)g(ro)m (w\),)h(ev)m(en)f(though)f(the)h(last)g(4)g(bits)227 4762 y(of)j(eac)m(h)g(b)m(yte)g(are)f(formally)f(not)h(de\014ned)f(and) h(should)e(all)h(b)s(e)g(set)i(=)f(0.)41 b(It)30 b(should)e(also)j(b)s (e)e(noted)h(that)227 4875 y(it)j(is)e(more)i(e\016cien)m(t)h(to)f (write)f('X')i(columns)d(an)i(en)m(tire)g(b)m(yte)g(at)h(a)f(time,)g (instead)f(of)h(bit)f(b)m(y)h(bit.)47 b(An)m(y)227 4988 y(of)31 b(the)g(CFITSIO)e(routines)g(that)j(write)e(to)h(columns)e (\(e.g.)43 b(\014ts)p 2481 4988 28 4 v 33 w(write)p 2717 4988 V 32 w(col)p 2860 4988 V 32 w(b)m(yt\))32 b(ma)m(y)f(b)s(e)f(used) g(for)g(this)227 5101 y(purp)s(ose.)60 b(These)36 b(routines)h(will)d (in)m(terpret)j('X')g(columns)f(as)h(though)g(they)h(w)m(ere)f('B')h (columns)e(\(e.g.,)227 5214 y('1X')c(through)d('8X')j(is)d(equiv)-5 b(alen)m(t)30 b(to)h('1B',)h(and)e('9X')h(through)f('16X')i(is)d(equiv) -5 b(alen)m(t)30 b(to)h('2B'\).)95 5468 y Fe(int)47 b (fits_write_col_bit)c(/)48 b(ffpclx)286 5581 y(\(fitsfile)e(*fptr,)g (int)h(colnum,)e(long)i(firstrow,)e(long)i(firstbit,)334 5694 y(long)g(nbits,)f(char)g(*larray,)g(>)h(int)g(*status\))p eop %%Page: 102 110 102 109 bop 0 299 a Fj(102)958 b Fh(CHAPTER)30 b(9.)112 b(SPECIALIZED)28 b(CFITSIO)h(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)0 555 y Fi(5)81 b Fj(W)-8 b(rite)34 b(the)g(descriptor)f(for)g(a)h(v)-5 b(ariable)33 b(length)g(column)g(in)f(a)j(binary)d(table.)51 b(This)32 b(routine)g(can)j(b)s(e)e(used)227 668 y(in)g(conjunction)g (with)f(\013gdes)i(to)h(enable)e(2)h(or)g(more)g(arra)m(ys)h(to)f(p)s (oin)m(t)f(to)i(the)f(same)g(storage)h(lo)s(cation)227 781 y(to)c(sa)m(v)m(e)h(storage)g(space)f(if)e(the)i(arra)m(ys)g(are)g (iden)m(tical.)191 1045 y Fe(int)47 b(fits_write_descript)42 b(/)48 b(ffpdes)382 1158 y(\(fitsfile)d(*fptr,)h(int)h(colnum,)f(long)h (rownum,)e(long)i(repeat,)430 1271 y(long)f(offset,)g(>)h(int)g (*status\))0 1567 y Fd(9.6.4)112 b(Read)38 b(Column)f(Data)h(Routines)0 1787 y Fj(Tw)m(o)28 b(t)m(yp)s(es)f(of)h(routines)e(are)i(pro)m(vided)e (to)i(get)h(the)e(column)g(data)h(whic)m(h)e(di\013er)g(in)g(the)i(w)m (a)m(y)h(unde\014ned)c(pixels)0 1900 y(are)40 b(handled.)65 b(The)39 b(\014rst)g(set)h(of)f(routines)f(\(\013gcv\))j(simply)c (return)h(an)h(arra)m(y)h(of)g(data)g(elemen)m(ts)f(in)f(whic)m(h)0 2013 y(unde\014ned)28 b(pixels)h(are)i(set)g(equal)f(to)h(a)g(v)-5 b(alue)30 b(sp)s(eci\014ed)f(b)m(y)i(the)f(user)g(in)f(the)i('n)m(ullv) -5 b(al')29 b(parameter.)41 b(If)30 b(n)m(ullv)-5 b(al)0 2126 y(=)22 b(0,)j(then)d(no)g(c)m(hec)m(ks)i(for)e(unde\014ned)e (pixels)h(will)f(b)s(e)i(p)s(erformed,)g(th)m(us)g(increasing)g(the)g (sp)s(eed)g(of)g(the)h(program.)0 2239 y(The)36 b(second)g(set)g(of)h (routines)d(\(\013gcf)7 b(\))38 b(returns)d(the)h(data)h(elemen)m(t)f (arra)m(y)h(and)e(in)g(addition)f(a)j(logical)e(arra)m(y)0 2351 y(of)e(\015ags)f(whic)m(h)f(de\014nes)h(whether)g(the)g(corresp)s (onding)f(data)i(pixel)d(is)i(unde\014ned.)44 b(See)33 b(App)s(endix)d(B)j(for)f(the)0 2464 y(de\014nition)c(of)j(the)f (parameters)h(used)e(in)g(these)i(routines.)0 2625 y(An)m(y)39 b(column,)g(regardless)f(of)h(it's)f(in)m(trinsic)e(data)k(t)m(yp)s(e,) h(ma)m(y)e(b)s(e)f(read)g(as)h(a)g(string.)65 b(It)38 b(should)f(b)s(e)h(noted)0 2737 y(ho)m(w)m(ev)m(er)32 b(that)f(reading)e(a)i(n)m(umeric)e(column)g(as)i(a)f(string)g(is)f(10) i(-)g(100)g(times)f(slo)m(w)m(er)h(than)f(reading)f(the)i(same)0 2850 y(column)f(as)i(a)g(n)m(um)m(b)s(er)e(due)h(to)h(the)g(large)g(o)m (v)m(erhead)g(in)f(constructing)g(the)h(formatted)g(strings.)43 b(The)31 b(displa)m(y)0 2963 y(format)26 b(of)g(the)h(returned)d (strings)h(will)e(b)s(e)j(determined)e(b)m(y)i(the)g(TDISPn)f(k)m(eyw)m (ord,)j(if)c(it)i(exists,)h(otherwise)e(b)m(y)0 3076 y(the)i(data)g(t)m(yp)s(e)f(of)h(the)f(column.)38 b(The)26 b(length)g(of)h(the)f(returned)f(strings)g(\(not)i(including)c(the)k(n) m(ull)d(terminating)0 3189 y(c)m(haracter\))38 b(can)e(b)s(e)g (determined)e(with)h(the)h(\014ts)p 1722 3189 28 4 v 33 w(get)p 1875 3189 V 34 w(col)p 2020 3189 V 32 w(displa)m(y)p 2332 3189 V 31 w(width)f(routine.)56 b(The)36 b(follo)m(wing)e(TDISPn)0 3302 y(displa)m(y)29 b(formats)h(are)h(curren)m(tly)e(supp)s(orted:)191 3566 y Fe(Iw.m)142 b(Integer)191 3679 y(Ow.m)g(Octal)46 b(integer)191 3792 y(Zw.m)142 b(Hexadecimal)45 b(integer)191 3905 y(Fw.d)142 b(Fixed)46 b(floating)g(point)191 4018 y(Ew.d)142 b(Exponential)45 b(floating)g(point)191 4131 y(Dw.d)142 b(Exponential)45 b(floating)g(point)191 4244 y(Gw.d)142 b(General;)46 b(uses)g(Fw.d)h(if)g(significance)d(not)j (lost,)g(else)f(Ew.d)0 4508 y Fj(where)37 b(w)h(is)f(the)h(width)e(in)h (c)m(haracters)i(of)f(the)h(displa)m(y)m(ed)d(v)-5 b(alues,)40 b(m)d(is)g(the)h(minim)m(um)e(n)m(um)m(b)s(er)g(of)i(digits)0 4621 y(displa)m(y)m(ed,)29 b(and)h(d)g(is)f(the)i(n)m(um)m(b)s(er)e(of) h(digits)f(to)i(the)g(righ)m(t)f(of)h(the)f(decimal.)40 b(The)30 b(.m)g(\014eld)f(is)g(optional.)0 4885 y Fi(1)81 b Fj(Read)29 b(elemen)m(ts)h(from)f(an)g(ASCI)s(I)f(or)i(binary)e (table)h(column)f(\(in)h(the)g(CDU\).)i(These)e(routines)f(return)h (the)227 4998 y(v)-5 b(alues)29 b(of)h(the)g(table)g(column)f(arra)m(y) h(elemen)m(ts.)41 b(Unde\014ned)28 b(arra)m(y)j(elemen)m(ts)f(will)d(b) s(e)i(returned)g(with)g(a)227 5111 y(v)-5 b(alue)29 b(=)f(n)m(ulv)-5 b(al,)28 b(unless)f(n)m(ulv)-5 b(al)27 b(=)h(0)i(\(or)f(=)f(')h(')g (for)g(\013gcvs\))g(in)f(whic)m(h)f(case)j(no)f(c)m(hec)m(king)h(for)e (unde\014ned)227 5224 y(v)-5 b(alues)27 b(will)e(b)s(e)i(p)s(erformed.) 39 b(The)27 b(ANYF)h(parameter)g(is)f(set)h(to)g(true)g(if)f(an)m(y)g (of)h(the)g(returned)f(elemen)m(ts)227 5337 y(are)k(unde\014ned.)95 5601 y Fe(int)47 b(fits_read_col_str)c(/)48 b(ffgcvs)286 5714 y(\(fitsfile)e(*fptr,)g(int)h(colnum,)e(long)i(firstrow,)e(long)i (firstelem,)p eop %%Page: 103 111 103 110 bop 0 299 a Fh(9.6.)72 b(SPECIALIZED)29 b(FITS)g(ASCI)s(I)g (AND)i(BINAR)-8 b(Y)32 b(T)-8 b(ABLE)30 b(R)m(OUTINES)933 b Fj(103)334 555 y Fe(long)47 b(nelements,)e(char)h(*nulstr,)g(>)h (char)g(**array,)f(int)g(*anynul,)334 668 y(int)h(*status\))95 894 y(int)g(fits_read_col_[log,byt,sht)o(,us)o(ht,i)o(nt,u)o(int)o (,lng)o(,uln)o(g,)41 b(lnglng,)46 b(flt,)h(dbl,)g(cmp,)f(dblcmp])g(/) 286 1007 y(ffgcv[l,b,i,ui,k,uk,j,uj,j)o(j,e)o(,d,c)o(,m])286 1120 y(\(fitsfile)g(*fptr,)g(int)h(colnum,)e(long)i(firstrow,)e(long)i (firstelem,)334 1233 y(long)g(nelements,)e(DTYPE)h(nulval,)g(>)h(DTYPE) g(*array,)f(int)g(*anynul,)334 1346 y(int)h(*status\))0 1632 y Fi(2)81 b Fj(Read)39 b(elemen)m(ts)h(and)f(n)m(ull)f(\015ags)i (from)f(an)g(ASCI)s(I)g(or)g(binary)f(table)i(column)e(\(in)h(the)h (CHDU\).)g(These)227 1745 y(routines)28 b(return)f(the)i(v)-5 b(alues)28 b(of)h(the)g(table)g(column)e(arra)m(y)j(elemen)m(ts.)40 b(An)m(y)29 b(unde\014ned)d(arra)m(y)k(elemen)m(ts)227 1858 y(will)h(ha)m(v)m(e)k(the)f(corresp)s(onding)d(n)m(ullarra)m(y)h (elemen)m(t)i(set)g(equal)f(to)h(TR)m(UE.)g(The)f(an)m(yn)m(ul)g (parameter)h(is)227 1971 y(set)d(to)g(true)f(if)g(an)m(y)h(of)f(the)h (returned)e(elemen)m(ts)i(are)f(unde\014ned.)95 2257 y Fe(int)47 b(fits_read_colnull_str)42 b(/)48 b(ffgcfs)286 2370 y(\(fitsfile)e(*fptr,)g(int)h(colnum,)e(long)i(firstrow,)e(long)i (firstelem,)334 2483 y(long)g(nelements,)e(>)i(char)g(**array,)e(char)i (*nullarray,)e(int)i(*anynul,)334 2596 y(int)g(*status\))95 2822 y(int)g(fits_read_colnull_[log,byt)o(,sh)o(t,us)o(ht,i)o(nt,)o (uint)o(,lng)o(,ul)o(ng,l)o(ngln)o(g,f)o(lt,d)o(bl,c)o(mp,)o(dblc)o (mp])41 b(/)286 2935 y(ffgcf[l,b,i,ui,k,uk,j,uj,j)o(j,e)o(,d,c)o(,m]) 286 3048 y(\(fitsfile)46 b(*fptr,)g(int)h(colnum,)e(long)i(firstrow,) 334 3161 y(long)g(firstelem,)e(long)h(nelements,)f(>)j(DTYPE)e(*array,) 334 3274 y(char)h(*nullarray,)d(int)j(*anynul,)f(int)h(*status\))0 3560 y Fi(3)81 b Fj(Read)24 b(an)g(arbitrary)f(data)i(subsection)e (from)h(an)g(N-dimensional)e(arra)m(y)j(in)e(a)h(binary)f(table)h(v)m (ector)i(column.)227 3673 y(Unde\014ned)21 b(pixels)g(in)g(the)i(arra)m (y)g(will)d(b)s(e)i(set)h(equal)g(to)g(the)g(v)-5 b(alue)22 b(of)h('n)m(ulv)-5 b(al',)23 b(unless)e(n)m(ulv)-5 b(al=0)21 b(in)g(whic)m(h)227 3786 y(case)37 b(no)e(testing)g(for)g(unde\014ned)e (pixels)g(will)g(b)s(e)i(p)s(erformed.)53 b(The)35 b(\014rst)g(and)f (last)h(ro)m(ws)h(in)e(the)h(table)227 3899 y(to)30 b(b)s(e)e(read)h (are)g(sp)s(eci\014ed)f(b)m(y)h(fpixel\(naxis+1\))d(and)j (lpixel\(naxis+1\),)e(and)h(hence)h(are)h(treated)g(as)f(the)227 4012 y(next)38 b(higher)e(dimension)f(of)j(the)f(FITS)g(N-dimensional)e (arra)m(y)-8 b(.)63 b(The)37 b(INC)h(parameter)g(sp)s(eci\014es)e(the) 227 4125 y(sampling)29 b(in)m(terv)-5 b(al)29 b(in)g(eac)m(h)j (dimension)c(b)s(et)m(w)m(een)j(the)f(data)h(elemen)m(ts)g(that)g(will) d(b)s(e)h(returned.)95 4411 y Fe(int)47 b(fits_read_subset_[byt,)42 b(sht,)47 b(usht,)f(int,)h(uint,)f(lng,)h(ulng,)f(lnglng,)g(flt,)h (dbl])f(/)286 4524 y(ffgsv[b,i,ui,k,uk,j,uj,jj,)o(e,d)o(])286 4637 y(\(fitsfile)g(*fptr,)g(int)h(colnum,)e(int)i(naxis,)f(long)h (*naxes,)f(long)h(*fpixel,)334 4750 y(long)g(*lpixel,)e(long)i(*inc,)f (DTYPE)h(nulval,)e(>)j(DTYPE)e(*array,)g(int)h(*anynul,)334 4863 y(int)g(*status\))0 5149 y Fi(4)81 b Fj(Read)24 b(an)g(arbitrary)f(data)i(subsection)e(from)h(an)g(N-dimensional)e (arra)m(y)j(in)e(a)h(binary)f(table)h(v)m(ector)i(column.)227 5262 y(An)m(y)34 b(Unde\014ned)e(pixels)g(in)h(the)g(arra)m(y)i(will)c (ha)m(v)m(e)k(the)f(corresp)s(onding)d('n)m(ullarra)m(y')i(elemen)m(t)h (set)g(equal)227 5375 y(to)40 b(TR)m(UE.)e(The)h(\014rst)e(and)h(last)h (ro)m(ws)f(in)g(the)g(table)h(to)g(b)s(e)f(read)h(are)g(sp)s(eci\014ed) d(b)m(y)j(fpixel\(naxis+1\))227 5488 y(and)i(lpixel\(naxis+1\),)i(and)e (hence)h(are)g(treated)g(as)g(the)g(next)g(higher)f(dimension)e(of)j (the)g(FITS)f(N-)227 5601 y(dimensional)f(arra)m(y)-8 b(.)78 b(The)41 b(INC)h(parameter)h(sp)s(eci\014es)e(the)i(sampling)d (in)m(terv)-5 b(al)42 b(in)f(eac)m(h)j(dimension)227 5714 y(b)s(et)m(w)m(een)31 b(the)g(data)g(elemen)m(ts)g(that)g(will)c (b)s(e)j(returned.)p eop %%Page: 104 112 104 111 bop 0 299 a Fj(104)958 b Fh(CHAPTER)30 b(9.)112 b(SPECIALIZED)28 b(CFITSIO)h(INTERF)-10 b(A)m(CE)30 b(R)m(OUTINES)95 555 y Fe(int)47 b(fits_read_subsetnull_[byt,)41 b(sht,)47 b(usht,)f(int,)h(uint,)f(lng,)h(ulng,)f(lnglng,)g(flt,)g(dbl])h(/)286 668 y(ffgsf[b,i,ui,k,uk,j,uj,jj,)o(e,d)o(])286 781 y(\(fitsfile)f (*fptr,)g(int)h(colnum,)e(int)i(naxis,)f(long)h(*naxes,)334 894 y(long)g(*fpixel,)e(long)i(*lpixel,)e(long)i(*inc,)f(>)i(DTYPE)e (*array,)334 1007 y(char)h(*nullarray,)d(int)j(*anynul,)f(int)h (*status\))0 1227 y Fi(5)81 b Fj(Read)35 b(bit)f(v)-5 b(alues)34 b(from)h(a)g(b)m(yte)h(\('B'\))g(or)f(bit)f(\(`X`\))i(table) f(column)f(\(in)g(the)h(CDU\).)h(Larra)m(y)g(is)e(an)g(arra)m(y)227 1340 y(of)g(logical)f(v)-5 b(alues)33 b(corresp)s(onding)f(to)i(the)g (sequence)g(of)g(bits)f(to)h(b)s(e)f(read.)51 b(If)33 b(larra)m(y)g(is)g(true)g(then)h(the)227 1453 y(corresp)s(onding)h(bit) h(w)m(as)h(set)h(to)f(1,)j(otherwise)c(the)h(bit)f(w)m(as)h(set)h(to)f (0.)61 b(The)37 b('X')g(column)f(in)f(a)j(FITS)227 1566 y(table)d(is)e(alw)m(a)m(ys)i(padded)f(out)h(to)g(a)g(m)m(ultiple)d(of) j(8)g(bits)e(where)h(the)h(bit)f(arra)m(y)h(starts)g(with)e(the)i(most) 227 1678 y(signi\014can)m(t)h(bit)f(of)i(the)g(b)m(yte)g(and)f(w)m (orks)g(do)m(wn)h(to)m(w)m(ards)g(the)g(1's)g(bit.)58 b(F)-8 b(or)37 b(example,)h(a)f('4X')h(arra)m(y)-8 b(,)227 1791 y(with)32 b(the)i(\014rst)e(bit)h(=)g(1)h(and)e(the)i(remaining)d (3)j(bits)e(=)h(0)h(is)e(equiv)-5 b(alen)m(t)33 b(to)h(the)g(8-bit)f (unsigned)e(b)m(yte)227 1904 y(v)-5 b(alue)30 b(of)g(128.)42 b(Note)31 b(that)g(in)d(the)j(case)g(of)f('X')g(columns,)f(CFITSIO)g (can)h(read)g(all)f(8)h(bits)f(of)h(eac)m(h)h(b)m(yte)227 2017 y(whether)h(they)h(are)g(formally)e(v)-5 b(alid)31 b(or)h(not.)48 b(Th)m(us)31 b(if)h(the)g(column)g(is)f(de\014ned)g(as)i ('4X',)h(and)e(one)h(calls)227 2130 y(\013gcx)d(with)e(\014rstbit=1)f (and)i(n)m(bits=8,)f(then)h(all)f(8)h(bits)f(will)e(b)s(e)j(read)g (from)f(the)h(\014rst)g(b)m(yte)g(\(as)h(opp)s(osed)227 2243 y(to)39 b(reading)e(the)h(\014rst)g(4)g(bits)f(from)h(the)g (\014rst)f(ro)m(w)h(and)g(then)f(the)i(\014rst)e(4)h(bits)f(from)h(the) g(next)g(ro)m(w\),)227 2356 y(ev)m(en)g(though)f(the)g(last)h(4)f(bits) f(of)i(eac)m(h)g(b)m(yte)g(are)f(formally)f(not)i(de\014ned.)60 b(It)37 b(should)e(also)i(b)s(e)g(noted)227 2469 y(that)f(it)e(is)h (more)g(e\016cien)m(t)g(to)h(read)f('X')h(columns)d(an)i(en)m(tire)g(b) m(yte)h(at)g(a)f(time,)h(instead)e(of)i(bit)e(b)m(y)h(bit.)227 2582 y(An)m(y)29 b(of)g(the)h(CFITSIO)d(routines)h(that)h(read)g (columns)f(\(e.g.)42 b(\014ts)p 2520 2582 28 4 v 32 w(read)p 2724 2582 V 33 w(col)p 2868 2582 V 33 w(b)m(yt\))29 b(ma)m(y)h(b)s(e)e (used)g(for)h(this)227 2695 y(purp)s(ose.)60 b(These)36 b(routines)h(will)d(in)m(terpret)j('X')g(columns)f(as)h(though)g(they)h (w)m(ere)f('B')h(columns)e(\(e.g.,)227 2808 y('8X')c(is)d(equiv)-5 b(alen)m(t)30 b(to)h('1B',)h(and)e('16X')i(is)d(equiv)-5 b(alen)m(t)30 b(to)h('2B'\).)95 3027 y Fe(int)47 b(fits_read_col_bit)c (/)48 b(ffgcx)286 3140 y(\(fitsfile)e(*fptr,)g(int)h(colnum,)e(long)i (firstrow,)e(long)i(firstbit,)334 3253 y(long)g(nbits,)f(>)h(char)g (*larray,)e(int)i(*status\))0 3473 y Fi(6)81 b Fj(Read)31 b(an)m(y)h(consecutiv)m(e)h(set)f(of)g(bits)e(from)i(an)f('X')h(or)g ('B')h(column)d(and)h(in)m(terpret)g(them)h(as)f(an)h(unsigned)227 3586 y(n-bit)g(in)m(teger.)47 b(n)m(bits)32 b(m)m(ust)g(b)s(e)g(less)g (than)h(16)g(or)g(32)g(in)e(\013gcxui)i(and)e(\013gcxuk,)j(resp)s (ectiv)m(ely)-8 b(.)47 b(If)32 b(nro)m(ws)227 3699 y(is)27 b(greater)i(than)f(1,)h(then)e(the)h(same)h(set)f(of)g(bits)f(will)e(b) s(e)i(read)h(from)f(eac)m(h)i(ro)m(w,)g(starting)f(with)e(\014rstro)m (w.)227 3812 y(The)k(bits)f(are)i(n)m(um)m(b)s(ered)e(with)g(1)i(=)f (the)h(most)f(signi\014can)m(t)g(bit)f(of)i(the)f(\014rst)g(elemen)m(t) h(of)f(the)h(column.)95 4032 y Fe(int)47 b(fits_read_col_bit_[usht,)42 b(uint])k(/)h(ffgcx[ui,uk])286 4145 y(\(fitsfile)f(*fptr,)g(int)h (colnum,)e(long)i(firstrow,)e(long,)i(nrows,)334 4258 y(long)g(firstbit,)e(long)i(nbits,)f(>)h(DTYPE)g(*array,)e(int)i (*status\))0 4478 y Fi(7)81 b Fj(Return)27 b(the)i(descriptor)e(for)i (a)g(v)-5 b(ariable)27 b(length)h(column)f(in)h(a)h(binary)d(table.)40 b(The)28 b(descriptor)g(consists)g(of)227 4591 y(2)k(in)m(teger)f (parameters:)42 b(the)31 b(n)m(um)m(b)s(er)f(of)h(elemen)m(ts)h(in)d (the)i(arra)m(y)h(and)e(the)h(starting)g(o\013set)h(relativ)m(e)f(to) 227 4704 y(the)d(start)f(of)g(the)h(heap.)39 b(The)27 b(\014rst)f(routine)g(returns)g(a)h(single)f(descriptor)g(whereas)h (the)g(second)g(routine)227 4816 y(returns)i(the)i(descriptors)e(for)h (a)h(range)g(of)f(ro)m(ws)h(in)e(the)h(table.)95 5036 y Fe(int)47 b(fits_read_descript)c(/)48 b(ffgdes)286 5149 y(\(fitsfile)e(*fptr,)g(int)h(colnum,)e(long)i(rownum,)f(>)h(long) g(*repeat,)525 5262 y(long)g(*offset,)e(int)i(*status\))95 5488 y(int)g(fits_read_descripts)c(/)k(ffgdess)286 5601 y(\(fitsfile)f(*fptr,)g(int)h(colnum,)e(long)i(firstrow,)e(long)i (nrows)f(>)i(long)e(*repeat,)525 5714 y(long)h(*offset,)e(int)i (*status\))p eop %%Page: 105 113 105 112 bop 0 1225 a Fg(Chapter)65 b(10)0 1687 y Fm(Extended)77 b(File)g(Name)g(Syn)-6 b(tax)0 2216 y Ff(10.1)136 b(Ov)l(erview)0 2466 y Fj(CFITSIO)30 b(supp)s(orts)f(an)j(extended)f(syn)m(tax)h(when)f (sp)s(ecifying)e(the)j(name)f(of)h(the)g(data)g(\014le)e(to)i(b)s(e)f (op)s(ened)g(or)0 2579 y(created)g(that)g(includes)d(the)j(follo)m (wing)e(features:)136 2813 y Fc(\017)46 b Fj(CFITSIO)40 b(can)i(read)f(IRAF)h(format)g(images)f(whic)m(h)f(ha)m(v)m(e)j(header) e(\014le)g(names)g(that)h(end)f(with)f(the)227 2926 y('.imh')d (extension,)i(as)f(w)m(ell)e(as)i(reading)e(and)h(writing)e(FITS)i (\014les,)h(This)e(feature)i(is)e(implemen)m(ted)g(in)227 3039 y(CFITSIO)29 b(b)m(y)i(\014rst)e(con)m(v)m(erting)j(the)e(IRAF)h (image)g(in)m(to)f(a)h(temp)s(orary)f(FITS)g(format)h(\014le)e(in)g (memory)-8 b(,)227 3152 y(then)35 b(op)s(ening)e(the)i(FITS)f(\014le.) 53 b(An)m(y)35 b(of)g(the)g(usual)e(CFITSIO)h(routines)f(then)i(ma)m(y) g(b)s(e)f(used)g(to)i(read)227 3265 y(the)31 b(image)f(header)g(or)h (data.)41 b(Similarly)-8 b(,)27 b(ra)m(w)j(binary)f(data)i(arra)m(ys)f (can)h(b)s(e)f(read)g(b)m(y)g(con)m(v)m(erting)h(them)227 3378 y(on)g(the)f(\015y)g(in)m(to)g(virtual)f(FITS)h(images.)136 3557 y Fc(\017)46 b Fj(FITS)37 b(\014les)g(on)g(the)h(in)m(ternet)g (can)g(b)s(e)f(read)g(\(and)g(sometimes)h(written\))f(using)f(the)i (FTP)-8 b(,)38 b(HTTP)-8 b(,)38 b(or)227 3670 y(R)m(OOT)30 b(proto)s(cols.)136 3849 y Fc(\017)46 b Fj(FITS)30 b(\014les)f(can)i(b) s(e)f(pip)s(ed)e(b)s(et)m(w)m(een)j(tasks)f(on)h(the)f(stdin)f(and)h (stdout)g(streams.)136 4028 y Fc(\017)46 b Fj(FITS)36 b(\014les)g(can)h(b)s(e)f(read)h(and)f(written)g(in)g(shared)g(memory) -8 b(.)60 b(This)35 b(can)i(p)s(oten)m(tially)f(ac)m(hiev)m(e)i(b)s (etter)227 4141 y(data)26 b(I/O)e(p)s(erformance)g(compared)h(to)h (reading)e(and)g(writing)e(the)j(same)h(FITS)e(\014les)f(on)i(magnetic) g(disk.)136 4320 y Fc(\017)46 b Fj(Compressed)30 b(FITS)f(\014les)h(in) f(gzip)h(or)g(Unix)f(COMPRESS)g(format)h(can)h(b)s(e)f(directly)f (read.)136 4499 y Fc(\017)46 b Fj(Output)28 b(FITS)h(\014les)f(can)h(b) s(e)g(written)f(directly)g(in)f(compressed)i(gzip)g(format,)h(th)m(us)e (sa)m(ving)h(disk)f(space.)136 4678 y Fc(\017)46 b Fj(FITS)26 b(table)g(columns)f(can)i(b)s(e)f(created,)i(mo)s(di\014ed,)e(or)g (deleted)g('on-the-\015y')h(as)g(the)g(table)f(is)f(op)s(ened)h(b)m(y) 227 4791 y(CFITSIO.)32 b(This)g(creates)j(a)e(virtual)f(FITS)h(\014le)f (con)m(taining)h(the)h(mo)s(di\014cations)d(that)j(is)f(then)g(op)s (ened)227 4904 y(b)m(y)e(the)f(application)f(program.)136 5083 y Fc(\017)46 b Fj(T)-8 b(able)28 b(ro)m(ws)f(ma)m(y)i(b)s(e)e (selected,)i(or)f(\014ltered)f(out,)h(on)g(the)g(\015y)f(when)g(the)h (table)g(is)f(op)s(ened)g(b)m(y)g(CFITSIO,)227 5196 y(based)22 b(on)f(an)g(user-sp)s(eci\014ed)f(expression.)37 b(Only)20 b(ro)m(ws)h(for)g(whic)m(h)g(the)h(expression)e(ev)-5 b(aluates)22 b(to)g('TR)m(UE')227 5309 y(are)31 b(retained)f(in)f(the)h (cop)m(y)i(of)e(the)h(table)f(that)h(is)e(op)s(ened)h(b)m(y)g(the)h (application)d(program.)136 5488 y Fc(\017)46 b Fj(Histogram)27 b(images)g(ma)m(y)g(b)s(e)f(created)h(on)f(the)h(\015y)f(b)m(y)g (binning)e(the)i(v)-5 b(alues)26 b(in)f(table)i(columns,)f(resulting) 227 5601 y(in)35 b(a)h(virtual)f(N-dimensional)e(FITS)j(image.)58 b(The)35 b(application)f(program)i(then)g(only)f(sees)h(the)h(FITS)227 5714 y(image)31 b(\(in)e(the)i(primary)d(arra)m(y\))k(instead)d(of)i (the)f(original)f(FITS)g(table.)1882 5942 y(105)p eop %%Page: 106 114 106 113 bop 0 299 a Fj(106)1528 b Fh(CHAPTER)29 b(10.)113 b(EXTENDED)30 b(FILE)h(NAME)f(SYNT)-8 b(AX)0 555 y Fj(The)39 b(latter)h(3)g(table)g(\014ltering)e(features)i(in)e(particular)g(add)h (v)m(ery)h(p)s(o)m(w)m(erful)e(data)j(pro)s(cessing)d(capabilities)0 668 y(directly)31 b(in)m(to)h(CFITSIO,)f(and)h(hence)h(in)m(to)f(ev)m (ery)h(task)g(that)g(uses)f(CFITSIO)f(to)i(read)f(or)h(write)e(FITS)h (\014les.)0 781 y(F)-8 b(or)29 b(example,)f(these)g(features)h (transform)e(a)h(v)m(ery)g(simple)e(program)i(that)g(just)g(copies)f (an)h(input)e(FITS)h(\014le)g(to)0 894 y(a)d(new)f(output)h(\014le)f (\(lik)m(e)g(the)h(`\014tscop)m(y')h(program)e(that)i(is)d(distributed) f(with)i(CFITSIO\))f(in)m(to)i(a)g(m)m(ultipurp)s(ose)0 1007 y(FITS)33 b(\014le)f(pro)s(cessing)g(to)s(ol.)50 b(By)33 b(app)s(ending)e(fairly)h(simple)f(quali\014ers)g(on)m(to)j (the)g(name)f(of)h(the)f(input)f(FITS)0 1120 y(\014le,)44 b(the)e(user)f(can)h(p)s(erform)e(quite)h(complex)h(table)f(editing)g (op)s(erations)g(\(e.g.,)46 b(create)d(new)e(columns,)j(or)0 1233 y(\014lter)31 b(out)i(ro)m(ws)f(in)f(a)h(table\))h(or)f(create)i (FITS)d(images)i(b)m(y)f(binning)d(or)j(histogramming)f(the)i(v)-5 b(alues)31 b(in)g(table)0 1346 y(columns.)46 b(In)32 b(addition,)f(these)i(functions)e(ha)m(v)m(e)j(b)s(een)e(co)s(ded)g (using)f(new)h(state-of-the)j(art)e(algorithms)e(that)0 1458 y(are,)g(in)e(some)i(cases,)g(10)h(-)e(100)i(times)e(faster)h (than)f(previous)f(widely)f(used)h(implemen)m(tations.)0 1619 y(Before)34 b(describing)d(the)j(complete)g(syn)m(tax)g(for)f(the) h(extended)f(FITS)g(\014le)f(names)h(in)f(the)i(next)g(section,)g(here) 0 1732 y(are)d(a)g(few)f(examples)g(of)g(FITS)g(\014le)f(names)i(that)f (giv)m(e)h(a)g(quic)m(k)f(o)m(v)m(erview)h(of)g(the)f(allo)m(w)m(ed)g (syn)m(tax:)136 1984 y Fc(\017)46 b Fe(myfile.fits)p Fj(:)38 b(the)30 b(simplest)f(case)i(of)g(a)g(FITS)e(\014le)h(on)g (disk)f(in)g(the)i(curren)m(t)f(directory)-8 b(.)136 2169 y Fc(\017)46 b Fe(myfile.imh)p Fj(:)i(op)s(ens)34 b(an)h(IRAF)g(format)g(image)h(\014le)e(and)g(con)m(v)m(erts)j(it)d(on) h(the)g(\015y)g(in)m(to)g(a)g(temp)s(orary)227 2282 y(FITS)30 b(format)h(image)f(in)f(memory)i(whic)m(h)e(can)h(then)g(b)s(e)g(read)g (with)f(an)m(y)i(other)g(CFITSIO)e(routine.)136 2467 y Fc(\017)46 b Fe(rawfile.dat[i512,512])p Fj(:)35 b(op)s(ens)30 b(a)g(ra)m(w)h(binary)d(data)j(arra)m(y)g(\(a)g(512)g(x)f(512)i(short)e (in)m(teger)g(arra)m(y)h(in)227 2580 y(this)h(case\))j(and)d(con)m(v)m (erts)j(it)d(on)h(the)g(\015y)g(in)m(to)g(a)g(temp)s(orary)g(FITS)f (format)h(image)h(in)d(memory)i(whic)m(h)227 2693 y(can)e(then)f(b)s(e) g(read)g(with)f(an)m(y)i(other)f(CFITSIO)f(routine.)136 2878 y Fc(\017)46 b Fe(myfile.fits.gz)p Fj(:)d(if)32 b(this)g(is)g(the)h(name)g(of)h(a)f(new)g(output)g(\014le,)g(the)g ('.gz')i(su\016x)d(will)e(cause)k(it)f(to)h(b)s(e)227 2991 y(compressed)c(in)f(gzip)h(format)h(when)e(it)h(is)g(written)f(to) i(disk.)136 3176 y Fc(\017)46 b Fe(myfile.fits.gz[events,)c(2])p Fj(:)35 b(op)s(ens)20 b(and)f(uncompresses)g(the)i(gzipp)s(ed)e(\014le) g(m)m(y\014le.\014ts)h(then)g(mo)m(v)m(es)227 3289 y(to)31 b(the)g(extension)f(with)f(the)i(k)m(eyw)m(ords)f(EXTNAME)h(=)f ('EVENTS')g(and)g(EXTVER)g(=)g(2.)136 3474 y Fc(\017)46 b Fe(-)p Fj(:)40 b(a)30 b(dash)f(\(min)m(us)f(sign\))h(signi\014es)f (that)i(the)g(input)e(\014le)g(is)h(to)h(b)s(e)f(read)h(from)f(the)h (stdin)e(\014le)h(stream,)h(or)227 3587 y(that)h(the)g(output)f(\014le) f(is)h(to)h(b)s(e)f(written)f(to)i(the)g(stdout)f(stream.)136 3772 y Fc(\017)46 b Fe(ftp://legacy.gsfc.nasa.go)o(v/te)o(st/v)o(ela)o (.fit)o(s)p Fj(:)k(FITS)37 b(\014les)g(in)g(an)m(y)i(ftp)e(arc)m(hiv)m (e)i(site)f(on)g(the)227 3885 y(in)m(ternet)30 b(ma)m(y)h(b)s(e)f (directly)f(op)s(ened)h(with)f(read-only)h(access.)136 4070 y Fc(\017)46 b Fe(http://legacy.gsfc.nasa.g)o(ov/s)o(oftw)o(are)o (/tes)o(t.fi)o(ts)p Fj(:)33 b(an)m(y)27 b(v)-5 b(alid)26 b(URL)h(to)h(a)g(FITS)e(\014le)h(on)g(the)227 4183 y(W)-8 b(eb)31 b(ma)m(y)g(b)s(e)f(op)s(ened)g(with)f(read-only)g(access.)136 4368 y Fc(\017)46 b Fe(root://legacy.gsfc.nasa.g)o(ov/t)o(est/)o(vel)o (a.fi)o(ts)p Fj(:)e(similar)33 b(to)j(ftp)f(access)i(except)f(that)g (it)f(pro-)227 4481 y(vides)29 b(write)h(as)g(w)m(ell)f(as)i(read)f (access)h(to)g(the)f(\014les)g(across)g(the)h(net)m(w)m(ork.)41 b(This)28 b(uses)i(the)h(ro)s(ot)f(proto)s(col)227 4594 y(dev)m(elop)s(ed)g(at)h(CERN.)136 4779 y Fc(\017)46 b Fe(shmem://h2[events])p Fj(:)j(op)s(ens)36 b(the)i(FITS)e(\014le)g (in)g(a)h(shared)f(memory)h(segmen)m(t)h(and)f(mo)m(v)m(es)h(to)g(the) 227 4892 y(EVENTS)30 b(extension.)136 5077 y Fc(\017)46 b Fe(mem://)p Fj(:)65 b(creates)44 b(a)g(scratc)m(h)g(output)f(\014le)f (in)g(core)i(computer)f(memory)-8 b(.)79 b(The)43 b(resulting)e ('\014le')i(will)227 5190 y(disapp)s(ear)24 b(when)g(the)i(program)f (exits,)h(so)g(this)e(is)h(mainly)e(useful)h(for)h(testing)h(purp)s (oses)d(when)i(one)g(do)s(es)227 5303 y(not)31 b(w)m(an)m(t)g(a)g(p)s (ermanen)m(t)f(cop)m(y)h(of)f(the)h(output)f(\014le.)136 5488 y Fc(\017)46 b Fe(myfile.fits[3;)e(Images\(10\)])p Fj(:)c(op)s(ens)30 b(a)i(cop)m(y)g(of)g(the)g(image)f(con)m(tained)h (in)e(the)i(10th)g(ro)m(w)f(of)h(the)227 5601 y('Images')38 b(column)e(in)g(the)h(binary)e(table)i(in)e(the)i(3th)g(extension)g(of) g(the)g(FITS)f(\014le.)59 b(The)37 b(virtual)e(\014le)227 5714 y(that)c(is)f(op)s(ened)f(b)m(y)i(the)f(application)f(just)h(con)m (tains)g(this)f(single)g(image)i(in)e(the)i(primary)d(arra)m(y)-8 b(.)p eop %%Page: 107 115 107 114 bop 0 299 a Fh(10.1.)73 b(O)m(VER)-10 b(VIEW)2995 b Fj(107)136 555 y Fc(\017)46 b Fe(myfile.fits[1:512:2,)d(1:512:2])p Fj(:)c(op)s(ens)30 b(a)h(section)g(of)h(the)f(input)e(image)i(ranging)f (from)g(the)h(1st)227 668 y(to)k(the)f(512th)h(pixel)d(in)h(X)h(and)g (Y,)g(and)f(selects)i(ev)m(ery)f(second)g(pixel)f(in)f(b)s(oth)h (dimensions,)g(resulting)227 781 y(in)c(a)i(256)h(x)e(256)i(pixel)c (input)h(image)h(in)g(this)f(case.)136 981 y Fc(\017)46 b Fe(myfile.fits[EVENTS][col)c(Rad)47 b(=)g(sqrt\(X**2)e(+)j(Y**2\)])p Fj(:)36 b(creates)27 b(and)d(op)s(ens)h(a)g(virtual)f(\014le)g(on)227 1094 y(the)i(\015y)f(that)i(is)e(iden)m(tical)f(to)j(m)m (y\014le.\014ts)e(except)h(that)h(it)e(will)e(con)m(tain)j(a)g(new)g (column)e(in)h(the)h(EVENTS)227 1207 y(extension)40 b(called)g('Rad')h (whose)f(v)-5 b(alue)40 b(is)g(computed)g(using)g(the)g(indicated)f (expression)h(whic)m(h)f(is)h(a)227 1320 y(function)29 b(of)i(the)f(v)-5 b(alues)30 b(in)f(the)i(X)f(and)g(Y)h(columns.)136 1520 y Fc(\017)46 b Fe(myfile.fits[EVENTS][PHA)c(>)47 b(5])p Fj(:)41 b(creates)33 b(and)d(op)s(ens)g(a)i(virtual)d(FITS)h (\014les)g(that)h(is)f(iden)m(tical)g(to)227 1633 y('m)m (y\014le.\014ts')39 b(except)i(that)f(the)f(EVENTS)g(table)g(will)e (only)h(con)m(tain)i(the)f(ro)m(ws)h(that)g(ha)m(v)m(e)g(v)-5 b(alues)39 b(of)227 1746 y(the)34 b(PHA)g(column)f(greater)i(than)e(5.) 52 b(In)33 b(general,)i(an)m(y)f(arbitrary)f(b)s(o)s(olean)f (expression)h(using)f(a)j(C)e(or)227 1859 y(F)-8 b(ortran-lik)m(e)29 b(syn)m(tax,)g(whic)m(h)e(ma)m(y)i(com)m(bine)f(AND)h(and)f(OR)f(op)s (erators,)i(ma)m(y)g(b)s(e)f(used)f(to)i(select)g(ro)m(ws)227 1972 y(from)h(a)h(table.)136 2172 y Fc(\017)46 b Fe (myfile.fits[EVENTS][bin)c(\(X,Y\)=1,2048,4])p Fj(:)34 b(creates)26 b(a)g(temp)s(orary)f(FITS)g(primary)e(arra)m(y)j(im-)227 2285 y(age)38 b(whic)m(h)d(is)h(computed)g(on)g(the)h(\015y)f(b)m(y)g (binning)d(\(i.e,)39 b(computing)c(the)i(2-dimensional)d(histogram\)) 227 2398 y(of)g(the)f(v)-5 b(alues)33 b(in)f(the)i(X)g(and)e(Y)i (columns)e(of)i(the)f(EVENTS)g(extension.)49 b(In)33 b(this)f(case)j(the)e(X)h(and)f(Y)227 2511 y(co)s(ordinates)g(range)h (from)f(1)h(to)g(2048)h(and)e(the)h(image)f(pixel)f(size)h(is)g(4)g (units)f(in)g(b)s(oth)h(dimensions,)f(so)227 2624 y(the)f(resulting)d (image)j(is)e(512)j(x)e(512)i(pixels)d(in)g(size.)136 2824 y Fc(\017)46 b Fj(The)31 b(\014nal)f(example)i(com)m(bines)f(man)m (y)g(of)h(these)g(feature)g(in)m(to)f(one)h(complex)f(expression)f (\(it)i(is)e(brok)m(en)227 2937 y(in)m(to)h(sev)m(eral)f(lines)f(for)h (clarit)m(y\):)370 3206 y Fe(ftp://legacy.gsfc.nasa.gov)o(/dat)o(a/s)o (ampl)o(e.fi)o(ts.)o(gz[E)o(VENT)o(S])370 3319 y([col)47 b(phacorr)f(=)h(pha)g(*)h(1.1)f(-)g(0.3][phacorr)e(>=)i(5.0)g(&&)g (phacorr)f(<=)h(14.0])370 3432 y([bin)g(\(X,Y\)=32])227 3701 y Fj(In)37 b(this)g(case,)k(CFITSIO)36 b(\(1\))j(copies)f(and)f (uncompresses)g(the)h(FITS)f(\014le)g(from)g(the)h(ftp)f(site)h(on)g (the)227 3814 y(legacy)f(mac)m(hine,)h(\(2\))f(mo)m(v)m(es)g(to)g(the)g ('EVENTS')f(extension,)h(\(3\))g(calculates)g(a)f(new)g(column)f (called)227 3927 y('phacorr',)30 b(\(4\))f(selects)g(the)g(ro)m(ws)g (in)e(the)i(table)g(that)g(ha)m(v)m(e)h(phacorr)e(in)f(the)i(range)g(5) g(to)h(14,)g(and)e(\014nally)227 4040 y(\(5\))35 b(bins)c(the)i (remaining)e(ro)m(ws)i(on)h(the)f(X)g(and)g(Y)g(column)f(co)s (ordinates,)i(using)d(a)j(pixel)d(size)i(=)g(32)h(to)227 4153 y(create)d(a)f(2D)g(image.)41 b(All)28 b(this)g(pro)s(cessing)g (is)h(completely)g(transparen)m(t)g(to)i(the)e(application)f(program,) 227 4266 y(whic)m(h)h(simply)f(sees)j(the)g(\014nal)e(2-D)i(image)g(in) e(the)h(primary)f(arra)m(y)i(of)f(the)h(op)s(ened)f(\014le.)0 4538 y(The)c(full)f(extended)i(CFITSIO)e(FITS)h(\014le)g(name)h(can)g (con)m(tain)g(sev)m(eral)g(di\013eren)m(t)g(comp)s(onen)m(ts)g(dep)s (ending)d(on)0 4651 y(the)31 b(con)m(text.)42 b(These)30 b(comp)s(onen)m(ts)h(are)g(describ)s(ed)d(in)h(the)h(follo)m(wing)f (sections:)0 4924 y Fe(When)47 b(creating)e(a)j(new)f(file:)143 5036 y(filetype://BaseFilename\(t)o(empl)o(ate)o(Name)o(\)[co)o(mpr)o (ess])0 5262 y(When)g(opening)e(an)j(existing)d(primary)h(array)g(or)i (image)e(HDU:)143 5375 y(filetype://BaseFilename\(o)o(utNa)o(me\))o ([HDU)o(loca)o(tio)o(n][I)o(mage)o(Sec)o(tion)o(])0 5601 y(When)h(opening)e(an)j(existing)d(table)i(HDU:)143 5714 y(filetype://BaseFilename\(o)o(utNa)o(me\))o([HDU)o(loca)o(tio)o(n][c)o (olFi)o(lte)o(r][r)o(owFi)o(lte)o(r][b)o(inSp)o(ec])p eop %%Page: 108 116 108 115 bop 0 299 a Fj(108)1528 b Fh(CHAPTER)29 b(10.)113 b(EXTENDED)30 b(FILE)h(NAME)f(SYNT)-8 b(AX)0 555 y Fj(The)41 b(\014let)m(yp)s(e,)j(BaseFilename,)h(outName,)g(HDUlo)s(cation,)g(and) c(ImageSection)h(comp)s(onen)m(ts,)j(if)c(presen)m(t,)0 668 y(m)m(ust)30 b(b)s(e)g(giv)m(en)h(in)e(that)i(order,)g(but)f(the)g (colFilter,)g(ro)m(wFilter,)h(and)e(binSp)s(ec)g(sp)s(eci\014ers)f(ma)m (y)k(follo)m(w)d(in)h(an)m(y)0 781 y(order.)39 b(Regardless)28 b(of)h(the)f(order,)g(ho)m(w)m(ev)m(er,)i(the)f(colFilter)e(sp)s (eci\014er,)g(if)g(presen)m(t,)i(will)d(b)s(e)h(pro)s(cessed)h(\014rst) f(b)m(y)0 894 y(CFITSIO,)i(follo)m(w)m(ed)h(b)m(y)g(the)h(ro)m(wFilter) f(sp)s(eci\014er,)f(and)g(\014nally)g(b)m(y)h(the)g(binSp)s(ec)e(sp)s (eci\014er.)0 1221 y Ff(10.2)136 b(Filet)l(yp)t(e)0 1471 y Fj(The)37 b(t)m(yp)s(e)g(of)g(\014le)f(determines)g(the)h(medium)e (on)i(whic)m(h)f(the)h(\014le)f(is)h(lo)s(cated)g(\(e.g.,)j(disk)c(or)h (net)m(w)m(ork\))h(and,)0 1584 y(hence,)f(whic)m(h)d(in)m(ternal)g (device)h(driv)m(er)f(is)g(used)g(b)m(y)h(CFITSIO)f(to)i(read)f(and/or) g(write)f(the)h(\014le.)55 b(Curren)m(tly)0 1697 y(supp)s(orted)29 b(t)m(yp)s(es)h(are)382 1913 y Fe(file://)93 b(-)48 b(file)e(on)i (local)e(magnetic)g(disk)g(\(default\))382 2026 y(ftp://)141 b(-)48 b(a)f(readonly)f(file)g(accessed)g(with)h(the)g(anonymous)e(FTP) i(protocol.)907 2139 y(It)g(also)g(supports)93 b (ftp://username:password@)o(host)o(nam)o(e/..)o(.)907 2252 y(for)47 b(accessing)e(password-protected)e(ftp)k(sites.)382 2365 y(http://)93 b(-)48 b(a)f(readonly)f(file)g(accessed)g(with)h(the) g(HTTP)f(protocol.)93 b(It)907 2478 y(does)46 b(not)95 b(support)46 b(username:password)d(like)k(the)g(ftp)f(driver.)907 2591 y(Proxy)g(HTTP)h(survers)f(are)h(supported)e(using)h(the)h (http_proxy)907 2704 y(environment)e(variable.)382 2817 y(root://)93 b(-)48 b(uses)e(the)h(CERN)g(root)g(protocol)e(for)i (writing)f(as)h(well)g(as)907 2930 y(reading)f(files)g(over)h(the)g (network.)382 3042 y(shmem://)e(-)j(opens)e(or)h(creates)f(a)i(file)e (which)h(persists)e(in)i(the)g(computer's)907 3155 y(shared)f(memory.) 382 3268 y(mem://)141 b(-)48 b(opens)e(a)i(temporary)d(file)i(in)g (core)f(memory.)94 b(The)47 b(file)907 3381 y(disappears)e(when)h(the)h (program)f(exits)h(so)g(this)f(is)i(mainly)907 3494 y(useful)e(for)h (test)f(purposes)g(when)h(a)g(permanent)e(output)h(file)907 3607 y(is)h(not)g(desired.)0 3824 y Fj(If)35 b(the)h(\014let)m(yp)s(e)f (is)f(not)i(sp)s(eci\014ed,)g(then)f(t)m(yp)s(e)h(\014le://)g(is)e (assumed.)56 b(The)35 b(double)f(slashes)h('//')i(are)f(optional)0 3937 y(and)30 b(ma)m(y)h(b)s(e)e(omitted)i(in)e(most)i(cases.)0 4220 y Fd(10.2.1)113 b(Notes)36 b(ab)s(out)j(HTTP)d(pro)m(xy)i(serv)m (ers)0 4439 y Fj(A)32 b(pro)m(xy)g(HTTP)f(serv)m(er)h(ma)m(y)h(b)s(e)e (used)g(b)m(y)h(de\014ning)e(the)i(address)f(\(URL\))i(and)e(p)s(ort)g (n)m(um)m(b)s(er)g(of)h(the)g(pro)m(xy)0 4552 y(serv)m(er)f(with)e(the) h(h)m(ttp)p 801 4552 28 4 v 33 w(pro)m(xy)g(en)m(vironmen)m(t)g(v)-5 b(ariable.)40 b(F)-8 b(or)31 b(example)191 4769 y Fe(setenv)46 b(http_proxy)f(http://heasarc.gsfc.nasa)o(.gov)o(:312)o(8)0 4985 y Fj(will)35 b(cause)j(CFITSIO)f(to)h(use)g(p)s(ort)f(3128)i(on)f (the)g(heasarc)g(pro)m(xy)g(serv)m(er)g(whenev)m(er)g(reading)f(a)h (FITS)f(\014le)0 5098 y(with)29 b(HTTP)-8 b(.)0 5382 y Fd(10.2.2)113 b(Notes)36 b(ab)s(out)j(the)e(ro)s(ot)g(\014let)m(yp)s (e)0 5601 y Fj(The)20 b(original)g(ro)s(otd)g(serv)m(er)h(can)h(b)s(e)e (obtained)g(from:)36 b Fe(ftp://root.cern.ch/root)o(/roo)o(td.t)o(ar.)o (gz)15 b Fj(but,)22 b(for)0 5714 y(it)32 b(to)i(w)m(ork)f(correctly)g (with)e(CFITSIO)h(one)h(has)f(to)i(use)e(a)i(mo)s(di\014ed)c(v)m (ersion)j(whic)m(h)e(supp)s(orts)g(a)i(command)p eop %%Page: 109 117 109 116 bop 0 299 a Fh(10.2.)73 b(FILETYPE)3037 b Fj(109)0 555 y(to)41 b(return)d(the)j(length)e(of)h(the)g(\014le.)69 b(This)38 b(mo)s(di\014ed)f(v)m(ersion)j(is)f(a)m(v)-5 b(ailable)39 b(in)g(ro)s(otd)g(sub)s(directory)f(in)h(the)0 668 y(CFITSIO)29 b(ftp)h(area)h(at)286 928 y Fe (ftp://legacy.gsfc.nasa.gov)o(/so)o(ftwa)o(re/f)o(its)o(io/c)o(/roo)o (t/r)o(ootd)o(.tar)o(.gz)o(.)0 1187 y Fj(This)i(small)f(serv)m(er)j(is) f(started)g(either)g(b)m(y)h(inetd)e(when)g(a)i(clien)m(t)f(requests)g (a)h(connection)g(to)g(a)f(ro)s(otd)h(serv)m(er)0 1300 y(or)30 b(b)m(y)g(hand)f(\(i.e.)41 b(from)30 b(the)g(command)g(line\).) 40 b(The)29 b(ro)s(otd)h(serv)m(er)h(w)m(orks)f(with)f(the)h(R)m(OOT)g (TNetFile)g(class.)0 1413 y(It)g(allo)m(ws)e(remote)j(access)f(to)h(R)m (OOT)e(database)h(\014les)e(in)g(either)h(read)h(or)f(write)g(mo)s(de.) 40 b(By)30 b(default)e(TNetFile)0 1526 y(assumes)38 b(p)s(ort)g(432)h (\(whic)m(h)e(requires)g(ro)s(otd)h(to)h(b)s(e)f(started)h(as)f(ro)s (ot\).)65 b(T)-8 b(o)39 b(run)e(ro)s(otd)h(via)g(inetd)f(add)h(the)0 1639 y(follo)m(wing)29 b(line)g(to)i(/etc/services:)95 1898 y Fe(rootd)238 b(432/tcp)0 2158 y Fj(and)30 b(to)h (/etc/inetd.conf,)h(add)e(the)g(follo)m(wing)f(line:)95 2417 y Fe(rootd)47 b(stream)f(tcp)h(nowait)f(root)h (/user/rdm/root/bin/root)o(d)42 b(rootd)k(-i)0 2677 y Fj(F)-8 b(orce)30 b(inetd)d(to)i(reread)f(its)g(conf)g(\014le)f(with)g Fe(kill)47 b(-HUP)g()p Fj(.)39 b(Y)-8 b(ou)28 b(can)h(also)f(start)h(ro)s(otd)f(b)m(y)g(hand)0 2790 y(running)34 b(directly)h(under)f(y)m(our)j(priv)-5 b(ate)36 b(accoun)m(t)h(\(no)g(ro)s(ot)g(system)f(privileges)e(needed\).)59 b(F)-8 b(or)37 b(example)f(to)0 2903 y(start)f(ro)s(otd)g(listening)d (on)j(p)s(ort)f(5151)j(just)d(t)m(yp)s(e:)49 b Fe(rootd)e(-p)g(5151)33 b Fj(Notice)j(that)g(no)e(&)h(is)e(needed.)54 b(Ro)s(otd)0 3016 y(will)28 b(go)j(in)m(to)f(bac)m(kground)g(b)m(y)h(itself.)95 3275 y Fe(Rootd)47 b(arguments:)191 3388 y(-i)763 b(says)47 b(we)g(were)f(started)g(by)h(inetd)191 3501 y(-p)g(port#)476 b(specifies)45 b(a)j(different)d(port)i(to)g(listen)f(on)191 3614 y(-d)h(level)476 b(level)46 b(of)i(debug)e(info)h(written)e(to)j (syslog)1050 3727 y(0)f(=)h(no)f(debug)f(\(default\))1050 3840 y(1)h(=)h(minimum)1050 3953 y(2)f(=)h(medium)1050 4066 y(3)f(=)h(maximum)0 4325 y Fj(Ro)s(otd)29 b(can)f(also)g(b)s(e)g (con\014gured)g(for)g(anon)m(ymous)g(usage)h(\(lik)m(e)f(anon)m(ymous)g (ftp\).)40 b(T)-8 b(o)29 b(setup)f(ro)s(otd)g(to)h(accept)0 4438 y(anon)m(ymous)h(logins)f(do)i(the)f(follo)m(wing)f(\(while)g(b)s (eing)g(logged)i(in)e(as)h(ro)s(ot\):)143 4698 y Fe(-)48 b(Add)f(the)f(following)g(line)g(to)i(/etc/passwd:)239 4924 y(rootd:*:71:72:Anonymous)41 b(rootd:/var/spool/rootd:/b)o(in/)o (fals)o(e)239 5149 y(where)46 b(you)h(may)g(modify)f(the)h(uid,)f(gid)h (\(71,)g(72\))g(and)g(the)g(home)f(directory)239 5262 y(to)h(suite)f(your)h(system.)143 5488 y(-)h(Add)f(the)f(following)g (line)g(to)i(/etc/group:)239 5714 y(rootd:*:72:rootd)p eop %%Page: 110 118 110 117 bop 0 299 a Fj(110)1528 b Fh(CHAPTER)29 b(10.)113 b(EXTENDED)30 b(FILE)h(NAME)f(SYNT)-8 b(AX)239 668 y Fe(where)46 b(the)h(gid)g(must)f(match)h(the)g(gid)g(in)g(/etc/passwd.) 143 894 y(-)h(Create)e(the)h(directories:)239 1120 y(mkdir)f (/var/spool/rootd)239 1233 y(mkdir)g(/var/spool/rootd/tmp)239 1346 y(chmod)g(777)h(/var/spool/rootd/tmp)239 1571 y(Where)f (/var/spool/rootd)d(must)k(match)f(the)h(rootd)g(home)f(directory)g(as) 239 1684 y(specified)f(in)i(the)g(rootd)f(/etc/passwd)f(entry.)143 1910 y(-)j(To)f(make)f(writeable)g(directories)e(for)j(anonymous)f(do,) h(for)f(example:)239 2136 y(mkdir)g(/var/spool/rootd/pub)239 2249 y(chown)g(rootd:rootd)f(/var/spool/rootd/pub)0 2492 y Fj(That's)d(all.)74 b(Sev)m(eral)42 b(additional)e(remarks:)64 b(y)m(ou)42 b(can)g(login)f(to)i(an)f(anon)m(ymous)f(serv)m(er)i (either)e(with)g(the)0 2605 y(names)31 b("anon)m(ymous")h(or)f("ro)s (otd".)43 b(The)31 b(passw)m(ord)f(should)f(b)s(e)i(of)g(t)m(yp)s(e)g (user@host.do.main.)42 b(Only)29 b(the)i(@)0 2718 y(is)d(enforced)g (for)h(the)f(time)h(b)s(eing.)38 b(In)28 b(anon)m(ymous)h(mo)s(de)f (the)g(top)h(of)g(the)g(\014le)e(tree)j(is)d(set)i(to)h(the)e(ro)s(otd) h(home)0 2831 y(directory)-8 b(,)38 b(therefore)f(only)e(\014les)h(b)s (elo)m(w)f(the)i(home)f(directory)g(can)g(b)s(e)g(accessed.)60 b(Anon)m(ymous)36 b(mo)s(de)g(only)0 2944 y(w)m(orks)30 b(when)g(the)g(serv)m(er)h(is)e(started)i(via)f(inetd.)0 3232 y Fd(10.2.3)113 b(Notes)36 b(ab)s(out)j(the)e(shmem)g(\014let)m (yp)s(e:)0 3451 y Fj(Shared)d(memory)h(\014les)f(are)h(curren)m(tly)f (supp)s(orted)f(on)i(most)h(Unix)e(platforms,)h(where)g(the)g(shared)f (memory)0 3564 y(segmen)m(ts)d(are)g(managed)g(b)m(y)f(the)g(op)s (erating)g(system)h(k)m(ernel)e(and)h(`liv)m(e')g(indep)s(enden)m(tly)d (of)k(pro)s(cesses.)40 b(They)0 3677 y(are)34 b(not)g(deleted)g(\(b)m (y)g(default\))f(when)g(the)h(pro)s(cess)f(whic)m(h)g(created)i(them)f (terminates,)g(although)g(they)g(will)0 3790 y(disapp)s(ear)d(if)h(the) i(system)f(is)f(reb)s(o)s(oted.)49 b(Applications)31 b(can)j(create)h(shared)d(memory)h(\014les)f(in)g(CFITSIO)g(b)m(y)0 3903 y(calling:)143 4146 y Fe(fit_create_file\(&fitsfile)o(ptr,)41 b("shmem://h2",)j(&status\);)0 4389 y Fj(where)25 b(the)g(ro)s(ot)h (`\014le')e(names)i(are)f(curren)m(tly)f(restricted)h(to)h(b)s(e)f ('h0',)i('h1',)g('h2',)g('h3',)f(etc.,)i(up)d(to)g(a)h(maxim)m(um)0 4502 y(n)m(um)m(b)s(er)20 b(de\014ned)f(b)m(y)i(the)g(the)g(v)-5 b(alue)21 b(of)g(SHARED)p 1746 4502 28 4 v 33 w(MAXSEG)g(\(equal)g(to)g (16)h(b)m(y)f(default\).)37 b(This)19 b(is)h(a)h(protot)m(yp)s(e)0 4615 y(implemen)m(tation)27 b(of)i(the)g(shared)f(memory)g(in)m (terface)h(and)f(a)h(more)g(robust)f(in)m(terface,)i(whic)m(h)d(will)f (ha)m(v)m(e)k(few)m(er)0 4728 y(restrictions)f(on)h(the)h(n)m(um)m(b)s (er)e(of)i(\014les)e(and)h(on)g(their)f(names,)i(ma)m(y)g(b)s(e)f(dev)m (elop)s(ed)f(in)g(the)i(future.)0 4888 y(When)23 b(op)s(ening)g(an)g (already)g(existing)g(FITS)g(\014le)g(in)f(shared)h(memory)h(one)g (calls)e(the)i(usual)f(CFITSIO)f(routine:)143 5132 y Fe(fits_open_file\(&fitsfilep)o(tr,)41 b("shmem://h7",)j(mode,)j (&status\))0 5375 y Fj(The)26 b(\014le)g(mo)s(de)h(can)g(b)s(e)f(READ)m (WRITE)h(or)g(READONL)-8 b(Y)28 b(just)e(as)h(with)e(disk)h(\014les.)38 b(More)28 b(than)e(one)h(pro)s(cess)0 5488 y(can)35 b(op)s(erate)g(on)f (READONL)-8 b(Y)35 b(mo)s(de)f(\014les)g(at)h(the)f(same)h(time.)53 b(CFITSIO)33 b(supp)s(orts)f(prop)s(er)h(\014le)h(lo)s(c)m(king)0 5601 y(\(b)s(oth)27 b(in)g(READONL)-8 b(Y)29 b(and)e(READ)m(WRITE)h(mo) s(des\),)h(so)f(calls)f(to)h(\014ts)p 2572 5601 V 33 w(op)s(en)p 2795 5601 V 32 w(\014le)f(ma)m(y)h(b)s(e)f(lo)s(c)m(k)m(ed) i(out)f(un)m(til)0 5714 y(another)j(other)f(pro)s(cess)g(closes)h(the)f (\014le.)p eop %%Page: 111 119 111 118 bop 0 299 a Fh(10.3.)73 b(BASE)30 b(FILENAME)2739 b Fj(111)0 555 y(When)30 b(an)g(application)f(is)g(\014nished)f (accessing)j(a)f(FITS)g(\014le)f(in)g(a)i(shared)e(memory)h(segmen)m (t,)i(it)e(ma)m(y)h(close)f(it)0 668 y(\(and)k(the)g(\014le)f(will)e (remain)h(in)h(the)h(system\))g(with)f(\014ts)p 1955 668 28 4 v 32 w(close)p 2174 668 V 33 w(\014le,)h(or)g(delete)g(it)g (with)e(\014ts)p 3191 668 V 33 w(delete)p 3456 668 V 33 w(\014le.)50 b(Ph)m(ys-)0 781 y(ical)34 b(deletion)g(is)g(p)s(ostp)s (oned)f(un)m(til)h(the)h(last)f(pro)s(cess)h(calls)f (\013clos/\013delt.)54 b(\014ts)p 2801 781 V 32 w(delete)p 3065 781 V 33 w(\014le)34 b(tries)h(to)g(obtain)g(a)0 894 y(READ)m(WRITE)f(lo)s(c)m(k)f(on)g(the)g(\014le)g(to)h(b)s(e)e (deleted,)i(th)m(us)f(it)g(can)g(b)s(e)g(blo)s(c)m(k)m(ed)g(if)f(the)i (ob)5 b(ject)34 b(w)m(as)f(not)h(op)s(ened)0 1007 y(in)29 b(READ)m(WRITE)i(mo)s(de.)0 1167 y(A)i(shared)f(memory)h(managemen)m(t) h(utilit)m(y)d(program)i(called)f(`smem',)h(is)f(included)e(with)i(the) h(CFITSIO)e(dis-)0 1280 y(tribution.)37 b(It)27 b(can)g(b)s(e)f(built)f (b)m(y)i(t)m(yping)f(`mak)m(e)i(smem';)g(then)f(t)m(yp)s(e)g(`smem)f (-h')h(to)h(get)g(a)f(list)e(of)i(v)-5 b(alid)25 b(options.)0 1393 y(Executing)36 b(smem)g(without)f(an)m(y)i(options)f(causes)g(it)g (to)h(list)e(all)g(the)i(shared)e(memory)i(segmen)m(ts)g(curren)m(tly)0 1506 y(residing)31 b(in)h(the)h(system)h(and)e(managed)i(b)m(y)f(the)h (shared)e(memory)h(driv)m(er.)48 b(T)-8 b(o)34 b(get)g(a)g(list)e(of)h (all)f(the)i(shared)0 1619 y(memory)c(ob)5 b(jects,)32 b(run)d(the)h(system)h(utilit)m(y)d(program)i(`ip)s(cs)g([-a]'.)0 1978 y Ff(10.3)136 b(Base)45 b(Filename)0 2233 y Fj(The)31 b(base)g(\014lename)g(is)f(the)i(name)f(of)h(the)f(\014le)g(optionally) e(including)f(the)k(director/sub)s(directory)d(path,)j(and)0 2346 y(in)d(the)i(case)g(of)g(`ftp',)f(`h)m(ttp',)i(and)d(`ro)s(ot')j (\014let)m(yp)s(es,)d(the)i(mac)m(hine)f(iden)m(ti\014er.)39 b(Examples:)191 2628 y Fe(myfile.fits)191 2741 y(!data.fits)191 2854 y(/data/myfile.fits)191 2967 y(fits.gsfc.nasa.gov/ftp/s)o(ampl)o (eda)o(ta/m)o(yfil)o(e.f)o(its.)o(gz)0 3248 y Fj(When)29 b(creating)g(a)g(new)f(output)h(\014le)f(on)h(magnetic)g(disk)e(\(of)j (t)m(yp)s(e)f(\014le://\))g(if)f(the)h(base)g(\014lename)f(b)s(egins)f (with)0 3361 y(an)34 b(exclamation)h(p)s(oin)m(t)e(\(!\))54 b(then)34 b(an)m(y)g(existing)g(\014le)f(with)g(that)i(same)g(basename) g(will)d(b)s(e)h(deleted)h(prior)f(to)0 3474 y(creating)h(the)g(new)g (FITS)f(\014le.)50 b(Otherwise)33 b(if)g(the)h(\014le)f(to)h(b)s(e)g (created)h(already)e(exists,)i(then)e(CFITSIO)g(will)0 3587 y(return)g(an)h(error)f(and)g(will)f(not)i(o)m(v)m(erwrite)g(the)g (existing)f(\014le.)51 b(Note)35 b(that)g(the)f(exclamation)g(p)s(oin)m (t,)g(')10 b(!',)36 b(is)d(a)0 3700 y(sp)s(ecial)26 b(UNIX)i(c)m (haracter,)j(so)d(if)e(it)i(is)f(used)g(on)g(the)h(command)g(line)e (rather)i(than)f(en)m(tered)h(at)h(a)f(task)h(prompt,)0 3813 y(it)i(m)m(ust)g(b)s(e)g(preceded)g(b)m(y)h(a)g(bac)m(kslash)f(to) h(force)g(the)g(UNIX)g(shell)d(to)j(pass)f(it)h(v)m(erbatim)f(to)h(the) g(application)0 3926 y(program.)0 4086 y(If)24 b(the)i(output)e(disk)g (\014le)g(name)h(ends)f(with)f(the)i(su\016x)f('.gz',)k(then)d(CFITSIO) e(will)f(compress)j(the)g(\014le)f(using)g(the)0 4199 y(gzip)g(compression)f(algorithm)g(b)s(efore)h(writing)e(it)i(to)h (disk.)37 b(This)22 b(can)j(reduce)f(the)g(amoun)m(t)h(of)f(disk)f (space)i(used)0 4312 y(b)m(y)34 b(the)h(\014le.)52 b(Note)36 b(that)f(this)f(feature)h(requires)e(that)i(the)f(uncompressed)g (\014le)f(b)s(e)h(constructed)h(in)e(memory)0 4425 y(b)s(efore)d(it)g (is)f(compressed)h(and)g(written)g(to)h(disk,)e(so)h(it)g(can)h(fail)e (if)g(there)i(is)e(insu\016cien)m(t)g(a)m(v)-5 b(ailable)30 b(memory)-8 b(.)0 4585 y(An)45 b(input)f(FITS)g(\014le)h(ma)m(y)h(b)s (e)f(compressed)g(with)g(the)g(gzip)g(or)h(Unix)e(compress)i (algorithms,)i(in)c(whic)m(h)0 4698 y(case)38 b(CFITSIO)e(will)f (uncompress)h(the)i(\014le)f(on)g(the)h(\015y)e(in)m(to)i(a)g(temp)s (orary)f(\014le)f(\(in)h(memory)g(or)g(on)h(disk\).)0 4811 y(Compressed)32 b(\014les)h(ma)m(y)h(only)e(b)s(e)h(op)s(ened)f (with)g(read-only)h(p)s(ermission.)47 b(When)33 b(sp)s(ecifying)e(the)j (name)f(of)h(a)0 4924 y(compressed)h(FITS)g(\014le)g(it)g(is)g(not)h (necessary)g(to)g(app)s(end)e(the)i(\014le)f(su\016x)f(\(e.g.,)39 b(`.gz')e(or)f(`.Z'\).)g(If)f(CFITSIO)0 5036 y(cannot)24 b(\014nd)e(the)h(input)e(\014le)i(name)g(without)f(the)h(su\016x,)h (then)f(it)g(will)e(automatically)i(searc)m(h)h(for)f(a)g(compressed)0 5149 y(\014le)35 b(with)f(the)i(same)g(ro)s(ot)g(name.)57 b(In)35 b(the)h(case)h(of)f(reading)f(ftp)g(and)g(h)m(ttp)h(t)m(yp)s(e) g(\014les,)g(CFITSIO)f(generally)0 5262 y(lo)s(oks)i(for)h(a)g (compressed)g(v)m(ersion)f(of)h(the)g(\014le)f(\014rst,)i(b)s(efore)e (trying)g(to)i(op)s(en)e(the)h(uncompressed)e(\014le.)63 b(By)0 5375 y(default,)36 b(CFITSIO)f(copies)g(\(and)h(uncompressed)e (if)h(necessary\))h(the)g(ftp)f(or)h(h)m(ttp)g(FITS)f(\014le)f(in)m(to) i(memory)0 5488 y(on)g(the)g(lo)s(cal)f(mac)m(hine)g(b)s(efore)h(op)s (ening)e(it.)57 b(This)34 b(will)f(fail)h(if)h(the)h(lo)s(cal)f(mac)m (hine)h(do)s(es)f(not)h(ha)m(v)m(e)h(enough)0 5601 y(memory)g(to)h (hold)e(the)h(whole)g(FITS)f(\014le,)j(so)e(in)f(this)g(case,)41 b(the)c(output)g(\014lename)f(sp)s(eci\014er)g(\(see)i(the)g(next)0 5714 y(section\))31 b(can)g(b)s(e)e(used)h(to)h(further)e(con)m(trol)i (ho)m(w)f(CFITSIO)f(reads)h(ftp)g(and)g(h)m(ttp)g(\014les.)p eop %%Page: 112 120 112 119 bop 0 299 a Fj(112)1528 b Fh(CHAPTER)29 b(10.)113 b(EXTENDED)30 b(FILE)h(NAME)f(SYNT)-8 b(AX)0 555 y Fj(If)32 b(the)h(input)e(\014le)h(is)g(an)h(IRAF)g(image)g(\014le)f(\(*.imh)g (\014le\))h(then)f(CFITSIO)f(will)g(automatically)h(con)m(v)m(ert)j(it) d(on)0 668 y(the)27 b(\015y)g(in)m(to)g(a)h(virtual)d(FITS)h(image)i(b) s(efore)f(it)f(is)g(op)s(ened)h(b)m(y)g(the)g(application)f(program.)39 b(IRAF)27 b(images)h(can)0 781 y(only)h(b)s(e)h(op)s(ened)g(with)f (READONL)-8 b(Y)31 b(\014le)e(access.)0 941 y(Similarly)-8 b(,)28 b(if)i(the)h(input)e(\014le)i(is)f(a)h(ra)m(w)g(binary)e(data)j (arra)m(y)-8 b(,)33 b(then)d(CFITSIO)g(will)e(con)m(v)m(ert)33 b(it)d(on)h(the)h(\015y)e(in)m(to)0 1054 y(a)38 b(virtual)e(FITS)i (image)g(with)e(the)i(basic)g(set)g(of)g(required)e(header)i(k)m(eyw)m (ords)g(b)s(efore)g(it)f(is)g(op)s(ened)g(b)m(y)h(the)0 1167 y(application)29 b(program)i(\(with)f(READONL)-8 b(Y)31 b(access\).)44 b(In)30 b(this)g(case)i(the)f(data)g(t)m(yp)s(e)g (and)g(dimensions)d(of)j(the)0 1280 y(image)c(m)m(ust)g(b)s(e)f(sp)s (eci\014ed)f(in)h(square)h(brac)m(k)m(ets)h(follo)m(wing)d(the)i (\014lename)f(\(e.g.)41 b(ra)m(w\014le.dat[ib512,512]\).)h(The)0 1393 y(\014rst)30 b(c)m(haracter)i(\(case)f(insensitiv)m(e\))e (de\014nes)h(the)g(data)h(t)m(yp)s(e)g(of)f(the)h(arra)m(y:)239 1671 y Fe(b)429 b(8-bit)46 b(unsigned)g(byte)239 1784 y(i)381 b(16-bit)46 b(signed)g(integer)239 1897 y(u)381 b(16-bit)46 b(unsigned)g(integer)239 2010 y(j)381 b(32-bit)46 b(signed)g(integer)239 2123 y(r)h(or)g(f)143 b(32-bit)46 b(floating)g(point)239 2235 y(d)381 b(64-bit)46 b(floating)g(point)0 2514 y Fj(An)40 b(optional)f(second)h(c)m(haracter)i(sp)s(eci\014es)d (the)i(b)m(yte)f(order)g(of)g(the)h(arra)m(y)g(v)-5 b(alues:)59 b(b)40 b(or)g(B)h(indicates)e(big)0 2626 y(endian)29 b(\(as)h(in)f(FITS)g(\014les)g(and)g(the)h(nativ)m(e)h(format)f(of)g (SUN)g(UNIX)g(w)m(orkstations)g(and)g(Mac)h(PCs\))e(and)h(l)f(or)0 2739 y(L)e(indicates)g(little)f(endian)g(\(nativ)m(e)j(format)e(of)h (DEC)g(OSF)f(w)m(orkstations)g(and)g(IBM)h(PCs\).)40 b(If)27 b(this)f(c)m(haracter)0 2852 y(is)f(omitted)g(then)g(the)h (arra)m(y)g(is)f(assumed)g(to)h(ha)m(v)m(e)h(the)f(nativ)m(e)f(b)m(yte) i(order)e(of)g(the)h(lo)s(cal)f(mac)m(hine.)39 b(These)25 b(data)0 2965 y(t)m(yp)s(e)35 b(c)m(haracters)h(are)g(then)e(follo)m(w) m(ed)h(b)m(y)f(a)i(series)e(of)h(one)g(or)g(more)g(in)m(teger)g(v)-5 b(alues)34 b(separated)i(b)m(y)e(commas)0 3078 y(whic)m(h)40 b(de\014ne)g(the)h(size)g(of)g(eac)m(h)h(dimension)d(of)i(the)g(ra)m(w) g(arra)m(y)-8 b(.)74 b(Arra)m(ys)41 b(with)e(up)h(to)i(5)f(dimensions)e (are)0 3191 y(curren)m(tly)30 b(supp)s(orted.)41 b(Finally)-8 b(,)30 b(a)h(b)m(yte)h(o\013set)g(to)g(the)f(p)s(osition)f(of)h(the)g (\014rst)f(pixel)g(in)g(the)h(data)h(\014le)e(ma)m(y)i(b)s(e)0 3304 y(sp)s(eci\014ed)g(b)m(y)h(separating)h(it)f(with)f(a)i(':')48 b(from)33 b(the)h(last)f(dimension)e(v)-5 b(alue.)50 b(If)33 b(omitted,)i(it)e(is)f(assumed)h(that)0 3417 y(the)i(o\013set)h(=)f(0.)54 b(This)34 b(parameter)h(ma)m(y)h(b)s(e)e (used)g(to)i(skip)d(o)m(v)m(er)j(an)m(y)g(header)e(information)g(in)f (the)i(\014le)f(that)0 3530 y(precedes)c(the)h(binary)e(data.)41 b(F)-8 b(urther)30 b(examples:)95 3808 y Fe(raw.dat[b10000])521 b(1-dimensional)45 b(10000)h(pixel)g(byte)h(array)95 3921 y(raw.dat[rb400,400,12])233 b(3-dimensional)45 b(floating)g(point) h(big-endian)f(array)95 4034 y(img.fits[ib512,512:2880])89 b(reads)47 b(the)g(512)g(x)g(512)g(short)f(integer)g(array)g(in)1336 4147 y(a)i(FITS)e(file,)h(skipping)e(over)i(the)g(2880)g(byte)f(header) 0 4425 y Fj(One)25 b(sp)s(ecial)e(case)j(of)f(input)e(\014le)h(is)g (where)h(the)g(\014lename)f(=)h(`-')h(\(a)f(dash)g(or)g(min)m(us)e (sign\))h(or)h('stdin')f(or)h('stdout',)0 4538 y(whic)m(h)c (signi\014es)g(that)j(the)f(input)d(\014le)i(is)g(to)i(b)s(e)e(read)g (from)h(the)g(stdin)e(stream,)k(or)e(written)e(to)j(the)f(stdout)g (stream)0 4650 y(if)33 b(a)h(new)g(output)f(\014le)g(is)g(b)s(eing)g (created.)52 b(In)33 b(the)h(case)h(of)f(reading)g(from)f(stdin,)g (CFITSIO)g(\014rst)g(copies)h(the)0 4763 y(whole)g(stream)i(in)m(to)f (a)g(temp)s(orary)g(FITS)f(\014le)h(\(in)f(memory)h(or)g(on)g(disk\),)g (and)g(subsequen)m(t)f(reading)g(of)i(the)0 4876 y(FITS)c(\014le)g(o)s (ccurs)h(in)e(this)h(cop)m(y)-8 b(.)49 b(When)33 b(writing)e(to)i (stdout,)h(CFITSIO)d(\014rst)h(constructs)h(the)g(whole)f(\014le)g(in)0 4989 y(memory)i(\(since)h(random)e(access)j(is)d(required\),)i(then)f (\015ushes)f(it)h(out)h(to)g(the)f(stdout)h(stream)g(when)e(the)i (\014le)0 5102 y(is)29 b(closed.)41 b(In)29 b(addition,)g(if)g(the)h (output)g(\014lename)f(=)h('-.gz')i(or)e('stdout.gz')h(then)f(it)g (will)d(b)s(e)j(gzip)f(compressed)0 5215 y(b)s(efore)h(b)s(eing)f (written)g(to)i(stdout.)0 5375 y(This)24 b(abilit)m(y)h(to)h(read)g (and)f(write)g(on)h(the)g(stdin)f(and)g(stdout)h(steams)g(allo)m(ws)g (FITS)f(\014les)g(to)h(b)s(e)g(pip)s(ed)d(b)s(et)m(w)m(een)0 5488 y(tasks)42 b(in)e(memory)h(rather)g(than)h(ha)m(ving)f(to)h (create)h(temp)s(orary)e(in)m(termediate)g(FITS)f(\014les)h(on)g(disk.) 72 b(F)-8 b(or)0 5601 y(example)27 b(if)e(task1)j(creates)h(an)e (output)f(FITS)g(\014le,)h(and)g(task2)g(reads)g(an)g(input)e(FITS)h (\014le,)h(the)g(FITS)f(\014le)g(ma)m(y)0 5714 y(b)s(e)k(pip)s(ed)e(b)s (et)m(w)m(een)j(the)f(2)h(tasks)g(b)m(y)f(sp)s(ecifying)p eop %%Page: 113 121 113 120 bop 0 299 a Fh(10.4.)73 b(OUTPUT)29 b(FILE)h(NAME)h(WHEN)g (OPENING)f(AN)h(EXISTING)f(FILE)876 b Fj(113)143 555 y Fe(task1)47 b(-)g(|)g(task2)g(-)0 783 y Fj(where)30 b(the)h(v)m(ertical)g(bar)g(is)e(the)i(Unix)f(piping)e(sym)m(b)s(ol.)41 b(This)29 b(assumes)h(that)i(the)f(2)g(tasks)g(read)g(the)g(name)g(of)0 896 y(the)g(FITS)e(\014le)h(o\013)g(of)h(the)g(command)f(line.)0 1224 y Ff(10.4)136 b(Output)44 b(File)i(Name)f(when)g(Op)t(ening)g(an)g (Existing)h(File)0 1474 y Fj(An)36 b(optional)g(output)g(\014lename)g (ma)m(y)i(b)s(e)e(sp)s(eci\014ed)f(in)g(paren)m(theses)i(immediately)e (follo)m(wing)g(the)i(base)g(\014le)0 1587 y(name)28 b(to)h(b)s(e)f(op)s(ened.)39 b(This)27 b(is)g(mainly)f(useful)h(in)g (those)h(cases)i(where)d(CFITSIO)g(creates)j(a)e(temp)s(orary)g(cop)m (y)0 1700 y(of)i(the)f(input)f(FITS)g(\014le)h(b)s(efore)g(it)g(is)f (op)s(ened)h(and)f(passed)h(to)h(the)g(application)e(program.)40 b(This)27 b(happ)s(ens)h(b)m(y)0 1813 y(default)h(when)h(op)s(ening)f (a)h(net)m(w)m(ork)h(FTP)g(or)f(HTTP-t)m(yp)s(e)g(\014le,)g(when)f (reading)g(a)i(compressed)f(FITS)g(\014le)f(on)0 1926 y(a)36 b(lo)s(cal)f(disk,)h(when)f(reading)g(from)h(the)g(stdin)e (stream,)k(or)d(when)g(a)i(column)d(\014lter,)j(ro)m(w)f(\014lter,)g (or)g(binning)0 2039 y(sp)s(eci\014er)28 b(is)g(included)f(as)j(part)f (of)g(the)h(input)e(\014le)g(sp)s(eci\014cation.)39 b(By)30 b(default)f(this)f(temp)s(orary)h(\014le)f(is)h(created)0 2152 y(in)g(memory)-8 b(.)41 b(If)29 b(there)h(is)f(not)h(enough)g (memory)g(to)h(create)g(the)g(\014le)e(cop)m(y)-8 b(,)31 b(then)f(CFITSIO)e(will)f(exit)j(with)f(an)0 2265 y(error.)45 b(In)32 b(these)g(cases)h(one)g(can)f(force)h(a)f(p)s(ermanen)m(t)g (\014le)f(to)i(b)s(e)e(created)i(on)f(disk,)f(instead)h(of)g(a)g(temp)s (orary)0 2378 y(\014le)37 b(in)f(memory)-8 b(,)40 b(b)m(y)d(supplying)d (the)k(name)g(in)e(paren)m(theses)i(immediately)e(follo)m(wing)g(the)h (base)h(\014le)f(name.)0 2490 y(The)30 b(output)g(\014lename)f(can)i (include)d(the)j(')10 b(!')41 b(clobb)s(er)29 b(\015ag.)0 2651 y(Th)m(us,)48 b(if)c(the)h(input)e(\014lename)h(to)h(CFITSIO)f (is:)69 b Fe(file1.fits.gz\(file2.fit)o(s\))39 b Fj(then)44 b(CFITSIO)g(will)0 2764 y(uncompress)39 b(`\014le1.\014ts.gz')i(in)m (to)f(the)g(lo)s(cal)f(disk)f(\014le)h(`\014le2.\014ts')h(b)s(efore)g (op)s(ening)e(it.)69 b(CFITSIO)38 b(do)s(es)i(not)0 2876 y(automatically)30 b(delete)h(the)f(output)g(\014le,)g(so)h(it)f(will)d (still)i(exist)h(after)h(the)f(application)f(program)h(exits.)0 3037 y(The)i(output)h(\014lename)f("mem://")j(is)d(also)h(allo)m(w)m (ed,)h(whic)m(h)d(will)g(write)h(the)h(output)f(\014le)g(in)m(to)h (memory)-8 b(,)35 b(and)0 3150 y(also)27 b(allo)m(w)f(write)g(access)i (to)g(the)f(\014le.)38 b(This)25 b('\014le')i(will)d(disapp)s(ear)h (when)h(it)g(is)g(closed,)h(but)f(this)g(ma)m(y)i(b)s(e)e(useful)0 3262 y(for)k(some)h(applications)d(whic)m(h)i(only)f(need)h(to)h(mo)s (dify)e(a)i(temp)s(orary)f(cop)m(y)h(of)f(the)h(\014le.)0 3423 y(In)k(some)i(cases,)h(sev)m(eral)e(di\013eren)m(t)g(temp)s(orary) f(FITS)h(\014les)f(will)e(b)s(e)i(created)i(in)e(sequence,)j(for)e (instance,)h(if)0 3535 y(one)g(op)s(ens)g(a)g(remote)h(\014le)e(using)g (FTP)-8 b(,)37 b(then)g(\014lters)f(ro)m(ws)h(in)f(a)i(binary)d(table)i (extension,)i(then)d(create)j(an)0 3648 y(image)e(b)m(y)g(binning)d(a)j (pair)f(of)h(columns.)59 b(In)36 b(this)g(case,)k(the)d(remote)h (\014le)e(will)e(b)s(e)i(copied)g(to)i(a)f(temp)s(orary)0 3761 y(lo)s(cal)h(\014le,)i(then)e(a)h(second)f(temp)s(orary)h(\014le)e (will)f(b)s(e)i(created)i(con)m(taining)e(the)g(\014ltered)g(ro)m(ws)g (of)h(the)g(table,)0 3874 y(and)c(\014nally)e(a)j(third)d(temp)s(orary) i(\014le)g(con)m(taining)f(the)i(binned)d(image)i(will)e(b)s(e)i (created.)57 b(In)34 b(cases)i(lik)m(e)f(this)0 3987 y(where)28 b(m)m(ultiple)e(\014les)h(are)i(created,)h(the)e(out\014le)g (sp)s(eci\014er)f(will)e(b)s(e)j(in)m(terpreted)g(the)g(name)g(of)h (the)f(\014nal)f(\014le)h(as)0 4100 y(describ)s(ed)g(b)s(elo)m(w,)i(in) f(descending)g(priorit)m(y:)136 4327 y Fc(\017)46 b Fj(as)29 b(the)g(name)g(of)g(the)g(\014nal)e(image)i(\014le)f(if)f(an)i(image)g (within)d(a)j(single)e(binary)g(table)i(cell)f(is)f(op)s(ened)h(or)h (if)227 4440 y(an)i(image)f(is)g(created)h(b)m(y)f(binning)e(a)i(table) h(column.)136 4617 y Fc(\017)46 b Fj(as)33 b(the)f(name)h(of)f(the)h (\014le)e(con)m(taining)h(the)g(\014ltered)f(table)i(if)e(a)i(column)e (\014lter)g(and/or)h(a)h(ro)m(w)f(\014lter)g(are)227 4730 y(sp)s(eci\014ed.)136 4907 y Fc(\017)46 b Fj(as)31 b(the)f(name)h(of)f(the)h(lo)s(cal)f(cop)m(y)h(of)f(the)h(remote)g(FTP) f(or)h(HTTP)e(\014le.)136 5084 y Fc(\017)46 b Fj(as)31 b(the)g(name)g(of)g(the)f(uncompressed)g(v)m(ersion)g(of)h(the)f(FITS)g (\014le,)g(if)g(a)h(compressed)f(FITS)g(\014le)g(on)h(lo)s(cal)227 5197 y(disk)e(has)h(b)s(een)g(op)s(ened.)136 5374 y Fc(\017)46 b Fj(otherwise,)30 b(the)h(output)f(\014lename)f(is)h(ignored.)0 5601 y(The)f(output)f(\014le)g(sp)s(eci\014er)g(is)g(useful)f(when)h (reading)g(FTP)h(or)g(HTTP-t)m(yp)s(e)g(FITS)f(\014les)g(since)g(it)h (can)g(b)s(e)g(used)0 5714 y(to)34 b(create)i(a)e(lo)s(cal)f(disk)f (cop)m(y)j(of)f(the)g(\014le)e(that)j(can)f(b)s(e)f(reused)g(in)f(the)i (future.)50 b(If)33 b(the)h(output)g(\014le)e(name)i(=)p eop %%Page: 114 122 114 121 bop 0 299 a Fj(114)1528 b Fh(CHAPTER)29 b(10.)113 b(EXTENDED)30 b(FILE)h(NAME)f(SYNT)-8 b(AX)0 555 y Fj(`*')36 b(then)f(a)g(lo)s(cal)f(\014le)g(with)g(the)h(same)g(name)g(as)g(the)h (net)m(w)m(ork)f(\014le)f(will)f(b)s(e)h(created.)56 b(Note)36 b(that)f(CFITSIO)0 668 y(will)27 b(b)s(eha)m(v)m(e)j (di\013eren)m(tly)f(dep)s(ending)e(on)j(whether)f(the)h(remote)g (\014le)f(is)g(compressed)g(or)h(not)g(as)g(sho)m(wn)f(b)m(y)h(the)0 781 y(follo)m(wing)f(examples:)136 1005 y Fc(\017)46 b Fe(ftp://remote.machine/tmp/)o(myfi)o(le.f)o(its)o(.gz\()o(*\))28 b Fj(-)35 b(the)g(remote)h(compressed)e(\014le)g(is)g(copied)g(to)227 1117 y(the)e(lo)s(cal)f(compressed)h(\014le)f(`m)m(y\014le.\014ts.gz',) i(whic)m(h)d(is)h(then)h(uncompressed)e(in)h(lo)s(cal)g(memory)g(b)s (efore)227 1230 y(b)s(eing)e(op)s(ened)h(and)g(passed)f(to)j(the)e (application)f(program.)136 1414 y Fc(\017)46 b Fe (ftp://remote.machine/tmp/)o(myfi)o(le.f)o(its)o(.gz\()o(myfi)o(le.)o (fits)o(\))33 b Fj(-)39 b(the)g(remote)h(compressed)f(\014le)227 1526 y(is)c(copied)g(and)g(uncompressed)g(in)m(to)g(the)h(lo)s(cal)f (\014le)g(`m)m(y\014le.\014ts'.)56 b(This)34 b(example)h(requires)g (less)g(lo)s(cal)227 1639 y(memory)21 b(than)g(the)g(previous)e (example)i(since)f(the)h(\014le)f(is)g(uncompressed)f(on)i(disk)f (instead)g(of)h(in)e(memory)-8 b(.)136 1822 y Fc(\017)46 b Fe(ftp://remote.machine/tmp/)o(myfi)o(le.f)o(its)o(\(myf)o(ile.)o (fit)o(s.gz)o(\))24 b Fj(-)30 b(this)f(will)e(usually)h(pro)s(duce)h (an)227 1935 y(error)h(since)g(CFITSIO)f(itself)g(cannot)i(compress)f (\014les.)0 2159 y(The)36 b(exact)i(b)s(eha)m(vior)d(of)i(CFITSIO)e(in) g(the)i(latter)f(case)i(dep)s(ends)c(on)j(the)f(t)m(yp)s(e)h(of)g(ftp)f (serv)m(er)g(running)e(on)0 2272 y(the)d(remote)g(mac)m(hine)f(and)g (ho)m(w)g(it)g(is)f(con\014gured.)40 b(In)30 b(some)h(cases,)g(if)e (the)i(\014le)e(`m)m(y\014le.\014ts.gz')j(exists)e(on)g(the)0 2385 y(remote)38 b(mac)m(hine,)g(then)f(the)g(serv)m(er)g(will)e(cop)m (y)i(it)g(to)g(the)h(lo)s(cal)e(mac)m(hine.)60 b(In)36 b(other)h(cases)h(the)f(ftp)g(serv)m(er)0 2498 y(will)c(automatically)j (create)h(and)f(transmit)f(a)h(compressed)g(v)m(ersion)f(of)h(the)g (\014le)f(if)g(only)g(the)h(uncompressed)0 2611 y(v)m(ersion)26 b(exists.)40 b(This)25 b(can)i(get)h(rather)f(confusing,)g(so)g(users)f (should)f(use)i(a)g(certain)g(amoun)m(t)h(of)f(caution)g(when)0 2723 y(using)33 b(the)i(output)f(\014le)g(sp)s(eci\014er)f(with)h(FTP)g (or)h(HTTP)f(\014le)g(t)m(yp)s(es,)i(to)f(mak)m(e)h(sure)e(they)h(get)h (the)f(b)s(eha)m(vior)0 2836 y(that)c(they)g(exp)s(ect.)0 3168 y Ff(10.5)136 b(T)-11 b(emplate)45 b(File)h(Name)g(when)e (Creating)j(a)e(New)g(File)0 3418 y Fj(When)38 b(a)h(new)f(FITS)g (\014le)g(is)g(created)h(with)f(a)g(call)g(to)i(\014ts)p 2101 3418 28 4 v 32 w(create)p 2369 3418 V 35 w(\014le,)f(the)g(name)g (of)g(a)g(template)g(\014le)e(ma)m(y)0 3531 y(b)s(e)i(supplied)e(in)i (paren)m(theses)h(immediately)e(follo)m(wing)g(the)j(name)f(of)g(the)g (new)f(\014le)g(to)i(b)s(e)e(created.)71 b(This)0 3644 y(template)26 b(is)e(used)h(to)h(de\014ne)f(the)h(structure)f(of)h(one) f(or)h(more)g(HDUs)g(in)e(the)i(new)f(\014le.)38 b(The)25 b(template)h(\014le)e(ma)m(y)0 3757 y(b)s(e)32 b(another)h(FITS)f (\014le,)h(in)f(whic)m(h)f(case)j(the)f(newly)f(created)i(\014le)e (will)e(ha)m(v)m(e)k(exactly)g(the)f(same)g(k)m(eyw)m(ords)g(in)0 3870 y(eac)m(h)25 b(HDU)g(as)g(in)e(the)h(template)h(FITS)e(\014le,)i (but)e(all)h(the)g(data)h(units)d(will)g(b)s(e)i(\014lled)e(with)g (zeros.)40 b(The)24 b(template)0 3983 y(\014le)h(ma)m(y)i(also)f(b)s(e) f(an)h(ASCI)s(I)e(text)j(\014le,)f(where)g(eac)m(h)h(line)d(\(in)h (general\))i(describ)s(es)d(one)i(FITS)f(k)m(eyw)m(ord)i(record.)0 4096 y(The)j(format)h(of)f(the)h(ASCI)s(I)e(template)h(\014le)g(is)f (describ)s(ed)f(in)i(the)g(follo)m(wing)f(T)-8 b(emplate)30 b(Files)g(c)m(hapter.)0 4427 y Ff(10.6)136 b(Image)46 b(Tile-Compression)g(Sp)t(eci\014cation)0 4677 y Fj(When)28 b(sp)s(ecifying)e(the)j(name)g(of)f(the)h(output)f(FITS)g(\014le)f(to)i (b)s(e)f(created,)i(the)f(user)f(can)g(indicate)g(that)h(images)0 4790 y(should)c(b)s(e)i(written)f(in)g(tile-compressed)g(format)i (\(see)g(section)f(5.5,)i(\\Primary)d(Arra)m(y)i(or)f(IMA)m(GE)h (Extension)0 4903 y(I/O)f(Routines"\))h(b)m(y)f(enclosing)f(the)i (compression)e(parameters)i(in)e(square)h(brac)m(k)m(ets)i(follo)m (wing)d(the)i(ro)s(ot)f(disk)0 5016 y(\014le)i(name.)41 b(Here)31 b(are)g(some)g(examples)f(of)g(the)h(syn)m(tax)g(for)f(sp)s (ecifying)e(tile-compressed)i(output)g(images:)191 5262 y Fe(myfile.fit[compress])185 b(-)48 b(use)f(Rice)f(algorithm)g(and)h (default)e(tile)i(size)191 5488 y(myfile.fit[compress)42 b(GZIP])47 b(-)g(use)g(the)g(specified)e(compression)g(algorithm;)191 5601 y(myfile.fit[compress)d(Rice])238 b(only)46 b(the)h(first)g (letter)f(of)h(the)g(algorithm)191 5714 y(myfile.fit[compress)42 b(PLIO])238 b(name)46 b(is)i(required.)p eop %%Page: 115 123 115 122 bop 0 299 a Fh(10.7.)73 b(HDU)31 b(LOCA)-8 b(TION)29 b(SPECIFICA)-8 b(TION)2019 b Fj(115)191 668 y Fe(myfile.fit[compress)42 b(Rice)47 b(100,100])141 b(-)48 b(use)e(100)h(x)h(100)f(pixel)f(tile)h (size)191 781 y(myfile.fit[compress)42 b(Rice)47 b(100,100;2])e(-)j(as) f(above,)f(and)h(use)g(noisebits)e(=)i(2)0 1114 y Ff(10.7)136 b(HDU)45 b(Lo)t(cation)g(Sp)t(eci\014cation)0 1364 y Fj(The)c(optional)f(HDU)j(lo)s(cation)e(sp)s(eci\014er)e(de\014nes)i (whic)m(h)f(HDU)i(\(Header-Data)i(Unit,)g(also)d(kno)m(wn)g(as)h(an)0 1477 y(`extension'\))35 b(within)c(the)k(FITS)e(\014le)g(to)i (initially)c(op)s(en.)51 b(It)34 b(m)m(ust)g(immediately)f(follo)m(w)g (the)h(base)h(\014le)e(name)0 1590 y(\(or)h(the)g(output)g(\014le)f (name)g(if)g(presen)m(t\).)52 b(If)33 b(it)g(is)g(not)h(sp)s(eci\014ed) f(then)g(the)h(\014rst)f(HDU)i(\(the)f(primary)e(arra)m(y\))0 1703 y(is)g(op)s(ened.)46 b(The)32 b(HDU)h(lo)s(cation)f(sp)s (eci\014er)f(is)h(required)f(if)g(the)i(colFilter,)f(ro)m(wFilter,)h (or)g(binSp)s(ec)d(sp)s(eci\014ers)0 1816 y(are)g(presen)m(t,)f(b)s (ecause)h(the)f(primary)e(arra)m(y)j(is)e(not)i(a)f(v)-5 b(alid)28 b(HDU)i(for)f(these)g(op)s(erations.)40 b(The)29 b(HDU)h(ma)m(y)g(b)s(e)0 1929 y(sp)s(eci\014ed)d(either)i(b)m(y)f (absolute)h(p)s(osition)e(n)m(um)m(b)s(er,)h(starting)h(with)e(0)j(for) e(the)h(primary)e(arra)m(y)-8 b(,)31 b(or)e(b)m(y)f(reference)0 2042 y(to)h(the)g(HDU)g(name,)g(and)f(optionally)-8 b(,)28 b(the)h(v)m(ersion)f(n)m(um)m(b)s(er)f(and)h(the)h(HDU)g(t)m(yp)s(e)g (of)f(the)h(desired)e(extension.)0 2155 y(The)32 b(lo)s(cation)f(of)h (an)g(image)h(within)c(a)k(single)d(cell)i(of)g(a)g(binary)f(table)h (ma)m(y)g(also)g(b)s(e)g(sp)s(eci\014ed,)f(as)h(describ)s(ed)0 2268 y(b)s(elo)m(w.)0 2428 y(The)26 b(absolute)g(p)s(osition)e(of)i (the)h(extension)f(is)f(sp)s(eci\014ed)f(either)i(b)m(y)g(enclosed)g (the)h(n)m(um)m(b)s(er)e(in)g(square)g(brac)m(k)m(ets)0 2541 y(\(e.g.,)k(`[1]')g(=)d(the)h(\014rst)f(extension)g(follo)m(wing)g (the)h(primary)d(arra)m(y\))k(or)f(b)m(y)f(preceded)h(the)g(n)m(um)m(b) s(er)e(with)h(a)h(plus)0 2654 y(sign)36 b(\(`+1'\).)63 b(T)-8 b(o)38 b(sp)s(ecify)e(the)h(HDU)h(b)m(y)g(name,)h(giv)m(e)f(the) f(name)h(of)f(the)h(desired)e(HDU)i(\(the)f(v)-5 b(alue)37 b(of)h(the)0 2766 y(EXTNAME)e(or)g(HDUNAME)h(k)m(eyw)m(ord\))g(and)f (optionally)e(the)i(extension)g(v)m(ersion)f(n)m(um)m(b)s(er)g(\(v)-5 b(alue)36 b(of)g(the)0 2879 y(EXTVER)27 b(k)m(eyw)m(ord\))i(and)e(the)h (extension)g(t)m(yp)s(e)f(\(v)-5 b(alue)28 b(of)g(the)g(XTENSION)f(k)m (eyw)m(ord:)40 b(IMA)m(GE,)29 b(ASCI)s(I)d(or)0 2992 y(T)-8 b(ABLE,)36 b(or)f(BINT)-8 b(ABLE\),)36 b(separated)f(b)m(y)g (commas)h(and)e(all)g(enclosed)h(in)f(square)h(brac)m(k)m(ets.)56 b(If)34 b(the)h(v)-5 b(alue)0 3105 y(of)34 b(EXTVER)f(and)f(XTENSION)h (are)h(not)f(sp)s(eci\014ed,)g(then)g(the)h(\014rst)e(extension)i(with) e(the)h(correct)i(v)-5 b(alue)33 b(of)0 3218 y(EXTNAME)39 b(is)f(op)s(ened.)67 b(The)38 b(extension)h(name)g(and)f(t)m(yp)s(e)i (are)f(not)h(case)g(sensitiv)m(e,)h(and)d(the)h(extension)0 3331 y(t)m(yp)s(e)29 b(ma)m(y)g(b)s(e)f(abbreviated)g(to)h(a)g(single)e (letter)i(\(e.g.,)i(I)d(=)g(IMA)m(GE)i(extension)e(or)g(primary)f(arra) m(y)-8 b(,)30 b(A)f(or)f(T)g(=)0 3444 y(ASCI)s(I)d(table)h(extension,)h (and)f(B)h(=)f(binary)f(table)h(BINT)-8 b(ABLE)27 b(extension\).)40 b(If)26 b(the)g(HDU)h(lo)s(cation)g(sp)s(eci\014er)0 3557 y(is)i(equal)h(to)h(`[PRIMAR)-8 b(Y]')32 b(or)f(`[P]',)g(then)f (the)h(primary)d(arra)m(y)j(\(the)g(\014rst)f(HDU\))h(will)d(b)s(e)i (op)s(ened.)0 3717 y(FITS)k(images)h(are)g(most)h(commonly)e(stored)h (in)f(the)h(primary)e(arra)m(y)i(or)g(an)g(image)g(extension,)h(but)e (images)0 3830 y(can)d(also)g(b)s(e)f(stored)h(as)h(a)f(v)m(ector)h(in) e(a)h(single)f(cell)g(of)h(a)h(binary)d(table)i(\(i.e.)42 b(eac)m(h)32 b(ro)m(w)f(of)g(the)h(v)m(ector)g(column)0 3943 y(con)m(tains)c(a)h(di\013eren)m(t)e(image\).)41 b(Suc)m(h)27 b(an)h(image)h(can)f(b)s(e)g(op)s(ened)f(with)g(CFITSIO)f (b)m(y)i(sp)s(ecifying)e(the)i(desired)0 4056 y(column)j(name)h(and)f (the)h(ro)m(w)g(n)m(um)m(b)s(er)f(after)h(the)g(binary)e(table)i(HDU)h (sp)s(eci\014er)d(as)i(sho)m(wn)g(in)e(the)i(follo)m(wing)0 4169 y(examples.)70 b(The)40 b(column)f(name)i(is)e(separated)i(from)f (the)h(HDU)g(sp)s(eci\014er)e(b)m(y)h(a)h(semicolon)e(and)h(the)h(ro)m (w)0 4282 y(n)m(um)m(b)s(er)29 b(is)g(enclosed)h(in)e(paren)m(theses.) 41 b(In)30 b(this)f(case)i(CFITSIO)d(copies)i(the)g(image)h(from)e(the) i(table)f(cell)f(in)m(to)0 4394 y(a)j(temp)s(orary)e(primary)g(arra)m (y)h(b)s(efore)g(it)g(is)f(op)s(ened.)43 b(The)30 b(application)g (program)h(then)g(just)g(sees)g(the)h(image)0 4507 y(in)h(the)i (primary)d(arra)m(y)-8 b(,)37 b(without)c(an)m(y)i(extensions.)52 b(The)34 b(particular)e(ro)m(w)j(to)g(b)s(e)e(op)s(ened)h(ma)m(y)h(b)s (e)f(sp)s(eci\014ed)0 4620 y(either)27 b(b)m(y)g(giving)f(an)h (absolute)g(in)m(teger)h(ro)m(w)g(n)m(um)m(b)s(er)e(\(starting)h(with)f (1)i(for)f(the)g(\014rst)g(ro)m(w\),)i(or)e(b)m(y)g(sp)s(ecifying)0 4733 y(a)33 b(b)s(o)s(olean)e(expression)g(that)i(ev)-5 b(aluates)33 b(to)g(TR)m(UE)g(for)f(the)g(desired)f(ro)m(w.)47 b(The)32 b(\014rst)f(ro)m(w)i(that)g(satis\014es)f(the)0 4846 y(expression)27 b(will)e(b)s(e)j(used.)39 b(The)28 b(ro)m(w)g(selection)g(expression)f(has)h(the)g(same)g(syn)m(tax)h(as)f (describ)s(ed)e(in)h(the)h(Ro)m(w)0 4959 y(Filter)i(Sp)s(eci\014er)e (section,)j(b)s(elo)m(w.)0 5119 y(Examples:)143 5375 y Fe(myfile.fits[3])44 b(-)k(open)e(the)h(3rd)g(HDU)g(following)e(the)i (primary)f(array)143 5488 y(myfile.fits+3)92 b(-)48 b(same)e(as)h (above,)f(but)h(using)g(the)g(FTOOLS-style)d(notation)143 5601 y(myfile.fits[EVENTS])f(-)k(open)g(the)g(extension)e(that)i(has)g (EXTNAME)e(=)j('EVENTS')143 5714 y(myfile.fits[EVENTS,)43 b(2])95 b(-)47 b(same)g(as)g(above,)f(but)h(also)g(requires)e(EXTVER)h (=)i(2)p eop %%Page: 116 124 116 123 bop 0 299 a Fj(116)1528 b Fh(CHAPTER)29 b(10.)113 b(EXTENDED)30 b(FILE)h(NAME)f(SYNT)-8 b(AX)143 555 y Fe(myfile.fits[events,2,b])42 b(-)47 b(same,)f(but)h(also)g(requires)f (XTENSION)f(=)j('BINTABLE')143 668 y(myfile.fits[3;)c(images\(17\)])h (-)i(opens)g(the)g(image)f(in)h(row)g(17)g(of)g(the)g('images')1527 781 y(column)f(in)i(the)e(3rd)h(extension)f(of)h(the)g(file.)143 894 y(myfile.fits[3;)d(images\(exposure)g(>)j(100\)])g(-)g(as)g(above,) f(but)h(opens)g(the)f(image)907 1007 y(in)h(the)g(first)f(row)h(that)g (has)g(an)g('exposure')e(column)h(value)907 1120 y(greater)g(than)g (100.)0 1449 y Ff(10.8)136 b(Image)46 b(Section)0 1699 y Fj(A)41 b(virtual)e(\014le)g(con)m(taining)h(a)h(rectangular)g (subsection)e(of)i(an)g(image)f(can)h(b)s(e)f(extracted)i(and)e(op)s (ened)g(b)m(y)0 1812 y(sp)s(ecifying)30 b(the)j(range)g(of)g(pixels)e (\(start:end\))i(along)g(eac)m(h)h(axis)e(to)h(b)s(e)f(extracted)i (from)e(the)h(original)d(image.)0 1925 y(One)g(can)h(also)g(sp)s(ecify) e(an)i(optional)f(pixel)f(incremen)m(t)h(\(start:end:step\))i(for)f (eac)m(h)h(axis)e(of)h(the)g(input)d(image.)0 2038 y(A)g(pixel)d(step)j (=)f(1)h(will)d(b)s(e)i(assumed)f(if)h(it)g(is)f(not)i(sp)s(eci\014ed.) 38 b(If)27 b(the)h(start)g(pixel)e(is)g(larger)i(then)f(the)h(end)e (pixel,)0 2151 y(then)32 b(the)g(image)g(will)d(b)s(e)i(\015ipp)s(ed)e (\(pro)s(ducing)h(a)i(mirror)f(image\))h(along)g(that)g(dimension.)43 b(An)32 b(asterisk,)g('*',)0 2264 y(ma)m(y)39 b(b)s(e)e(used)h(to)h(sp) s(ecify)e(the)h(en)m(tire)g(range)h(of)f(an)h(axis,)h(and)d('-*')j (will)35 b(\015ip)i(the)h(en)m(tire)g(axis.)64 b(The)38 b(input)0 2377 y(image)30 b(can)g(b)s(e)f(in)f(the)i(primary)e(arra)m (y)-8 b(,)31 b(in)d(an)h(image)h(extension,)g(or)g(con)m(tained)f(in)g (a)h(v)m(ector)h(cell)e(of)h(a)g(binary)0 2490 y(table.)39 b(In)25 b(the)h(later)g(2)g(cases)h(the)f(extension)g(name)g(or)f(n)m (um)m(b)s(er)g(m)m(ust)h(b)s(e)f(sp)s(eci\014ed)f(b)s(efore)i(the)g (image)g(section)0 2603 y(sp)s(eci\014er.)0 2763 y(Examples:)95 2996 y Fe(myfile.fits[1:512:2,)43 b(2:512:2])i(-)95 b(open)47 b(a)h(256x256)d(pixel)i(image)668 3109 y(consisting)e(of)i(the)g(odd)g (numbered)f(columns)g(\(1st)g(axis\))h(and)668 3222 y(the)g(even)g (numbered)e(rows)i(\(2nd)g(axis\))f(of)h(the)g(image)f(in)i(the)668 3335 y(primary)e(array)g(of)i(the)e(file.)95 3561 y(myfile.fits[*,)e (512:256])i(-)h(open)g(an)g(image)g(consisting)e(of)i(all)g(the)g (columns)668 3674 y(in)g(the)g(input)g(image,)f(but)h(only)f(rows)h (256)g(through)f(512.)668 3787 y(The)h(image)f(will)h(be)g(flipped)f (along)g(the)h(2nd)g(axis)g(since)668 3900 y(the)g(starting)f(pixel)g (is)h(greater)f(than)h(the)g(ending)f(pixel.)95 4125 y(myfile.fits[*:2,)e(512:256:2])h(-)i(same)g(as)g(above)f(but)h (keeping)f(only)668 4238 y(every)h(other)f(row)h(and)g(column)f(in)h (the)g(input)f(image.)95 4464 y(myfile.fits[-*,)e(*])j(-)h(copy)e(the)h (entire)f(image,)g(flipping)g(it)h(along)668 4577 y(the)g(first)f (axis.)95 4803 y(myfile.fits[3][1:256,1:256)o(])c(-)47 b(opens)g(a)g(subsection)e(of)i(the)g(image)g(that)668 4916 y(is)g(in)h(the)e(3rd)h(extension)f(of)h(the)g(file.)95 5142 y(myfile.fits[4;)d(images\(12\)][1:10,1:10])e(-)48 b(open)e(an)h(image)g(consisting)286 5255 y(of)h(the)e(first)h(10)g (pixels)f(in)h(both)g(dimensions.)e(The)i(original)286 5367 y(image)g(resides)f(in)h(the)g(12th)f(row)h(of)g(the)g('images')f (vector)286 5480 y(column)g(in)i(the)f(table)f(in)h(the)g(4th)g (extension)e(of)i(the)g(file.)0 5714 y Fj(When)23 b(CFITSIO)f(op)s(ens) h(an)g(image)g(section)h(it)f(\014rst)g(creates)h(a)g(temp)s(orary)f (\014le)g(con)m(taining)g(the)g(image)h(section)p eop %%Page: 117 125 117 124 bop 0 299 a Fh(10.9.)73 b(COLUMN)30 b(AND)h(KEYW)m(ORD)g(FIL)-8 b(TERING)30 b(SPECIFICA)-8 b(TION)1030 b Fj(117)0 555 y(plus)31 b(a)j(cop)m(y)g(of)g(an)m(y)g(other)f(HDUs)h(in)e(the)i (\014le.)49 b(This)31 b(temp)s(orary)i(\014le)g(is)f(then)h(op)s(ened)g (b)m(y)g(the)h(application)0 668 y(program,)28 b(so)g(it)f(is)f(not)i (p)s(ossible)d(to)j(write)f(to)h(or)g(mo)s(dify)e(the)h(input)f(\014le) g(when)h(sp)s(ecifying)e(an)j(image)g(section.)0 781 y(Note)39 b(that)f(CFITSIO)e(automatically)h(up)s(dates)g(the)g(w)m (orld)g(co)s(ordinate)g(system)h(k)m(eyw)m(ords)f(in)f(the)i(header)0 894 y(of)33 b(the)h(image)f(section,)h(if)e(they)i(exist,)g(so)f(that)h (the)f(co)s(ordinate)g(asso)s(ciated)h(with)e(eac)m(h)i(pixel)d(in)h (the)i(image)0 1007 y(section)d(will)c(b)s(e)j(computed)g(correctly)-8 b(.)0 1360 y Ff(10.9)136 b(Column)45 b(and)f(Keyw)l(ord)i(Filtering)g (Sp)t(eci\014cation)0 1615 y Fj(The)27 b(optional)g(column/k)m(eyw)m (ord)h(\014ltering)e(sp)s(eci\014er)g(is)h(used)g(to)i(mo)s(dify)d(the) i(column)f(structure)g(and/or)h(the)0 1728 y(header)38 b(k)m(eyw)m(ords)h(in)e(the)i(HDU)g(that)h(w)m(as)f(selected)g(with)e (the)i(previous)e(HDU)i(lo)s(cation)f(sp)s(eci\014er.)64 b(This)0 1840 y(\014ltering)40 b(sp)s(eci\014er)g(m)m(ust)i(b)s(e)f (enclosed)h(in)e(square)i(brac)m(k)m(ets)h(and)e(can)h(b)s(e)f (distinguished)d(from)k(a)g(general)0 1953 y(ro)m(w)d(\014lter)f(sp)s (eci\014er)f(\(describ)s(ed)g(b)s(elo)m(w\))h(b)m(y)h(the)g(fact)h (that)f(it)f(b)s(egins)f(with)h(the)h(string)f('col)h(')g(and)f(is)g (not)0 2066 y(immediately)27 b(follo)m(w)m(ed)h(b)m(y)g(an)g(equals)g (sign.)39 b(The)28 b(original)e(\014le)h(is)h(not)g(c)m(hanged)h(b)m(y) f(this)g(\014ltering)e(op)s(eration,)0 2179 y(and)40 b(instead)g(the)h(mo)s(di\014cations)e(are)i(made)f(on)h(a)g(cop)m(y)g (of)g(the)g(input)e(FITS)h(\014le)f(\(usually)g(in)g(memory\),)0 2292 y(whic)m(h)32 b(also)h(con)m(tains)g(a)g(cop)m(y)h(of)f(all)f(the) i(other)f(HDUs)h(in)d(the)i(\014le.)48 b(This)32 b(temp)s(orary)g (\014le)g(is)g(passed)h(to)h(the)0 2405 y(application)c(program)i(and)f (will)e(p)s(ersist)h(only)h(un)m(til)f(the)i(\014le)f(is)g(closed)h(or) g(un)m(til)e(the)i(program)f(exits,)i(unless)0 2518 y(the)e(out\014le)e (sp)s(eci\014er)g(\(see)i(ab)s(o)m(v)m(e\))h(is)e(also)g(supplied.)0 2678 y(The)h(column/k)m(eyw)m(ord)g(\014lter)f(can)h(b)s(e)g(used)f(to) i(p)s(erform)e(the)i(follo)m(wing)d(op)s(erations.)43 b(More)32 b(than)f(one)g(op)s(er-)0 2791 y(ation)f(ma)m(y)h(b)s(e)f(sp) s(eci\014ed)f(b)m(y)h(separating)g(them)g(with)g(semi-colons.)136 3068 y Fc(\017)46 b Fj(Cop)m(y)36 b(only)f(a)h(sp)s(eci\014ed)f(list)f (of)i(columns)f(columns)f(to)j(the)f(\014ltered)f(input)f(\014le.)56 b(The)36 b(list)e(of)i(column)227 3181 y(name)c(should)e(b)s(e)i (separated)g(b)m(y)g(semi-colons.)46 b(Wild)30 b(card)i(c)m(haracters)i (ma)m(y)e(b)s(e)g(used)f(in)g(the)h(column)227 3294 y(names)37 b(to)h(matc)m(h)g(m)m(ultiple)d(columns.)60 b(If)37 b(the)g(expression) f(con)m(tains)i(b)s(oth)e(a)i(list)d(of)j(columns)e(to)i(b)s(e)227 3406 y(included)f(and)h(columns)g(to)h(b)s(e)g(deleted,)i(then)d(all)g (the)h(columns)f(in)g(the)h(original)e(table)i(except)h(the)227 3519 y(explicitly)28 b(deleted)i(columns)f(will)e(app)s(ear)j(in)f(the) h(\014ltered)f(table)h(\(i.e.,)h(there)f(is)g(no)g(need)f(to)i (explicitly)227 3632 y(list)e(the)i(columns)e(to)i(b)s(e)f(included)d (if)j(an)m(y)g(columns)f(are)i(b)s(eing)e(deleted\).)136 3837 y Fc(\017)46 b Fj(Delete)31 b(a)e(column)f(or)h(k)m(eyw)m(ord)h(b) m(y)f(listing)e(the)i(name)g(preceded)g(b)m(y)g(a)g(min)m(us)f(sign)g (or)h(an)g(exclamation)227 3950 y(mark)c(\(!\),)h(e.g.,)i('-TIME')d (will)d(delete)j(the)f(TIME)h(column)e(if)g(it)i(exists,)g(otherwise)f (the)h(TIME)f(k)m(eyw)m(ord.)227 4063 y(An)35 b(error)f(is)g(returned)f (if)h(neither)f(a)j(column)d(nor)h(k)m(eyw)m(ord)h(with)f(this)f(name)i (exists.)53 b(Note)36 b(that)g(the)227 4176 y(exclamation)25 b(p)s(oin)m(t,)h(')10 b(!',)27 b(is)d(a)h(sp)s(ecial)f(UNIX)h(c)m (haracter,)j(so)d(if)f(it)h(is)f(used)g(on)h(the)g(command)g(line)e (rather)227 4289 y(than)33 b(en)m(tered)h(at)g(a)g(task)g(prompt,)f(it) g(m)m(ust)g(b)s(e)g(preceded)g(b)m(y)g(a)h(bac)m(kslash)f(to)h(force)g (the)f(UNIX)h(shell)227 4401 y(to)d(ignore)f(it.)136 4606 y Fc(\017)46 b Fj(Rename)29 b(an)g(existing)e(column)g(or)i(k)m (eyw)m(ord)g(with)e(the)i(syn)m(tax)g('NewName)h(==)e(OldName'.)39 b(An)28 b(error)227 4719 y(is)i(returned)f(if)g(neither)h(a)g(column)f (nor)h(k)m(eyw)m(ord)h(with)e(this)h(name)g(exists.)136 4924 y Fc(\017)46 b Fj(App)s(end)37 b(a)j(new)f(column)e(or)j(k)m(eyw)m (ord)f(to)h(the)f(table.)67 b(T)-8 b(o)40 b(create)g(a)g(column,)g(giv) m(e)g(the)f(new)g(name,)227 5036 y(optionally)32 b(follo)m(w)m(ed)g(b)m (y)h(the)g(data)h(t)m(yp)s(e)f(in)e(paren)m(theses,)j(follo)m(w)m(ed)f (b)m(y)g(a)g(single)f(equals)g(sign)g(and)g(an)227 5149 y(expression)i(to)i(b)s(e)e(used)g(to)i(compute)f(the)g(v)-5 b(alue)34 b(\(e.g.,)k('new)m(col\(1J\))e(=)f(0')g(will)e(create)j(a)f (new)g(32-bit)227 5262 y(in)m(teger)h(column)d(called)i('new)m(col')g (\014lled)e(with)h(zeros\).)55 b(The)35 b(data)g(t)m(yp)s(e)h(is)e(sp)s (eci\014ed)f(using)g(the)j(same)227 5375 y(syn)m(tax)j(that)g(is)e (allo)m(w)m(ed)h(for)g(the)g(v)-5 b(alue)38 b(of)g(the)g(FITS)f(TF)m (ORMn)h(k)m(eyw)m(ord)h(\(e.g.,)j('I',)d('J',)f('E',)h('D',)227 5488 y(etc.)66 b(for)38 b(binary)e(tables,)41 b(and)c('I8',)k(F12.3',)i ('E20.12',)g(etc.)65 b(for)38 b(ASCI)s(I)f(tables\).)65 b(If)37 b(the)i(data)g(t)m(yp)s(e)227 5601 y(is)34 b(not)h(sp)s (eci\014ed)e(then)h(an)g(appropriate)g(data)h(t)m(yp)s(e)g(will)d(b)s (e)i(c)m(hosen)h(dep)s(ending)d(on)i(the)h(form)f(of)h(the)227 5714 y(expression)43 b(\(ma)m(y)h(b)s(e)f(a)h(c)m(haracter)i(string,)g (logical,)h(bit,)f(long)d(in)m(teger,)48 b(or)43 b(double)g(column\).) 79 b(An)p eop %%Page: 118 126 118 125 bop 0 299 a Fj(118)1528 b Fh(CHAPTER)29 b(10.)113 b(EXTENDED)30 b(FILE)h(NAME)f(SYNT)-8 b(AX)227 555 y Fj(appropriate)38 b(v)m(ector)j(coun)m(t)e(\(in)f(the)h(case)h(of)f (binary)e(tables\))i(will)d(also)j(b)s(e)f(added)g(if)g(not)h (explicitly)227 668 y(sp)s(eci\014ed.)227 819 y(When)26 b(creating)g(a)g(new)f(k)m(eyw)m(ord,)j(the)e(k)m(eyw)m(ord)g(name)g(m) m(ust)g(b)s(e)f(preceded)g(b)m(y)h(a)g(p)s(ound)e(sign)g('#',)k(and)227 932 y(the)h(expression)e(m)m(ust)h(ev)-5 b(aluate)29 b(to)g(a)g(scalar)f(\(i.e.,)h(cannot)g(ha)m(v)m(e)h(a)f(column)e(name)h (in)f(the)i(expression\).)227 1045 y(The)j(commen)m(t)i(string)e(for)g (the)h(k)m(eyw)m(ord)h(ma)m(y)f(b)s(e)f(sp)s(eci\014ed)f(in)g(paren)m (theses)i(immediately)e(follo)m(wing)227 1158 y(the)c(k)m(eyw)m(ord)g (name)f(\(instead)g(of)h(supplying)c(a)k(data)g(t)m(yp)s(e)g(as)f(in)f (the)i(case)g(of)g(creating)g(a)g(new)f(column\).)136 1348 y Fc(\017)46 b Fj(Recompute)f(\(o)m(v)m(erwrite\))h(the)e(v)-5 b(alues)43 b(in)g(an)h(existing)g(column)f(or)h(k)m(eyw)m(ord)g(b)m(y)g (giving)g(the)g(name)227 1461 y(follo)m(w)m(ed)30 b(b)m(y)h(an)f (equals)g(sign)f(and)h(an)g(arithmetic)g(expression.)0 1722 y(The)23 b(expression)f(that)j(is)d(used)h(when)g(app)s(ending)e (or)i(recomputing)g(columns)f(or)i(k)m(eyw)m(ords)g(can)g(b)s(e)f (arbitrarily)0 1835 y(complex)35 b(and)h(ma)m(y)g(b)s(e)f(a)h(function) f(of)h(other)g(header)g(k)m(eyw)m(ord)g(v)-5 b(alues)35 b(and)g(other)h(columns)f(\(in)g(the)h(same)0 1948 y(ro)m(w\).)63 b(The)37 b(full)e(syn)m(tax)k(and)e(a)m(v)-5 b(ailable)37 b(functions)f(for)h(the)h(expression)e(are)i(describ)s(ed)e(b)s(elo)m (w)h(in)f(the)i(ro)m(w)0 2061 y(\014lter)29 b(sp)s(eci\014cation)h (section.)0 2221 y(F)-8 b(or)30 b(complex)g(or)f(commonly)g(used)g(op)s (erations,)h(one)f(can)h(also)g(place)g(the)f(op)s(erations)g(in)m(to)h (an)f(external)h(text)0 2334 y(\014le)g(and)g(imp)s(ort)f(it)h(in)m(to) h(the)g(column)f(\014lter)f(using)h(the)h(syn)m(tax)g('[col)g (@\014lename.txt]'.)42 b(The)31 b(op)s(erations)f(can)0 2447 y(extend)c(o)m(v)m(er)i(m)m(ultiple)c(lines)h(of)h(the)h(\014le,)g (but)e(m)m(ultiple)f(op)s(erations)i(m)m(ust)g(still)f(b)s(e)g (separated)i(b)m(y)g(semicolons.)0 2560 y(An)m(y)h(lines)f(in)g(the)h (external)h(text)g(\014le)e(that)i(b)s(egin)e(with)g(2)i(slash)e(c)m (haracters)j(\('//'\))g(will)c(b)s(e)h(ignored)h(and)f(ma)m(y)0 2673 y(b)s(e)j(used)f(to)i(add)f(commen)m(ts)h(in)m(to)g(the)f(\014le.) 0 2833 y(Examples:)143 3095 y Fe([col)47 b(Time;rate])713 b(-)47 b(only)g(the)g(Time)g(and)g(rate)f(columns)g(will)1670 3208 y(appear)h(in)g(the)g(filtered)e(input)i(file.)143 3434 y([col)g(Time;*raw])713 b(-)47 b(include)f(the)h(Time)g(column)f (and)h(any)g(other)1670 3546 y(columns)f(whose)h(name)f(ends)h(with)g ('raw'.)143 3772 y([col)g(-TIME;)f(Good)h(==)g(STATUS])141 b(-)47 b(deletes)f(the)h(TIME)g(column)f(and)1670 3885 y(renames)g(the)h(status)f(column)g(to)i('Good')143 4111 y([col)f(PI=PHA)f(*)h(1.1)g(+)h(0.2])285 b(-)47 b(creates)f(new)h(PI)g (column)f(from)h(PHA)g(values)143 4337 y([col)g(rate)f(=)i (rate/exposure])139 b(-)48 b(recomputes)d(the)i(rate)f(column)g(by)i (dividing)1670 4450 y(it)g(by)f(the)g(EXPOSURE)e(keyword)h(value.)0 4786 y Ff(10.10)136 b(Ro)l(w)46 b(Filtering)g(Sp)t(eci\014cation)0 5036 y Fj(When)29 b(en)m(tering)g(the)g(name)g(of)g(a)g(FITS)f(table)h (that)h(is)d(to)j(b)s(e)e(op)s(ened)h(b)m(y)f(a)i(program,)f(an)g (optional)f(ro)m(w)h(\014lter)0 5149 y(ma)m(y)i(b)s(e)g(sp)s(eci\014ed) e(to)i(select)g(a)h(subset)e(of)h(the)g(ro)m(ws)f(in)g(the)h(table.)42 b(A)31 b(temp)s(orary)f(new)g(FITS)g(\014le)g(is)g(created)0 5262 y(on)25 b(the)h(\015y)e(whic)m(h)g(con)m(tains)h(only)g(those)h (ro)m(ws)f(for)g(whic)m(h)f(the)h(ro)m(w)g(\014lter)g(expression)f(ev) -5 b(aluates)25 b(to)h(true.)39 b(\(The)0 5375 y(primary)25 b(arra)m(y)i(and)f(an)m(y)g(other)h(extensions)f(in)f(the)i(input)e (\014le)g(are)i(also)g(copied)f(to)h(the)f(temp)s(orary)h(\014le\).)38 b(The)0 5488 y(original)27 b(FITS)i(\014le)f(is)g(closed)h(and)f(the)i (new)e(virtual)g(\014le)g(is)g(op)s(ened)g(b)m(y)h(the)h(application)d (program.)40 b(The)29 b(ro)m(w)0 5601 y(\014lter)36 b(expression)g(is)h (enclosed)g(in)f(square)h(brac)m(k)m(ets)i(follo)m(wing)d(the)h(\014le) g(name)g(and)g(extension)g(name)g(\(e.g.,)0 5714 y('\014le.\014ts[ev)m (en)m(ts][GRADE==50]')28 b(selects)d(only)f(those)i(ro)m(ws)f(where)f (the)h(GRADE)h(column)e(v)-5 b(alue)24 b(equals)g(50\).)p eop %%Page: 119 127 119 126 bop 0 299 a Fh(10.10.)73 b(R)m(O)m(W)31 b(FIL)-8 b(TERING)31 b(SPECIFICA)-8 b(TION)1936 b Fj(119)0 555 y(When)33 b(dealing)f(with)g(tables)g(where)h(eac)m(h)h(ro)m(w)f(has)g (an)g(asso)s(ciated)h(time)f(and/or)g(2D)g(spatial)g(p)s(osition,)f (the)0 668 y(ro)m(w)g(\014lter)g(expression)e(can)j(also)f(b)s(e)g (used)f(to)i(select)g(ro)m(ws)f(based)g(on)g(the)g(times)g(in)f(a)h(Go) s(o)s(d)g(Time)f(In)m(terv)-5 b(als)0 781 y(\(GTI\))31 b(extension,)f(or)g(on)h(spatial)e(p)s(osition)g(as)h(giv)m(en)h(in)e (a)h(SA)m(O-st)m(yle)h(region)f(\014le.)0 1090 y Fd(10.10.1)113 b(General)37 b(Syn)m(tax)0 1313 y Fj(The)32 b(ro)m(w)h(\014ltering)e (expression)h(can)h(b)s(e)f(an)h(arbitrarily)d(complex)i(series)g(of)h (op)s(erations)f(p)s(erformed)g(on)g(con-)0 1426 y(stan)m(ts,)39 b(k)m(eyw)m(ord)e(v)-5 b(alues,)37 b(and)f(column)f(data)j(tak)m(en)f (from)f(the)h(sp)s(eci\014ed)d(FITS)i(T)-8 b(ABLE)37 b(extension.)58 b(The)0 1539 y(expression)36 b(m)m(ust)i(ev)-5 b(aluate)38 b(to)h(a)f(b)s(o)s(olean)f(v)-5 b(alue)37 b(for)g(eac)m(h)i(ro)m(w)f(of)g(the)f(table,)j(where)d(a)h(v)-5 b(alue)38 b(of)f(F)-10 b(ALSE)0 1652 y(means)30 b(that)h(the)g(ro)m(w)f (will)e(b)s(e)i(excluded.)0 1812 y(F)-8 b(or)34 b(complex)f(or)h (commonly)e(used)h(\014lters,)g(one)h(can)g(place)f(the)h(expression)e (in)m(to)h(a)h(text)g(\014le)f(and)g(imp)s(ort)e(it)0 1925 y(in)m(to)37 b(the)f(ro)m(w)h(\014lter)f(using)f(the)i(syn)m(tax)g ('[@\014lename.txt]'.)60 b(The)36 b(expression)g(can)g(b)s(e)g (arbitrarily)e(complex)0 2038 y(and)27 b(extend)i(o)m(v)m(er)g(m)m (ultiple)d(lines)g(of)i(the)h(\014le.)39 b(An)m(y)28 b(lines)e(in)h(the)h(external)g(text)h(\014le)e(that)i(b)s(egin)e(with) g(2)h(slash)0 2151 y(c)m(haracters)k(\('//'\))g(will)c(b)s(e)i(ignored) f(and)h(ma)m(y)h(b)s(e)f(used)f(to)i(add)f(commen)m(ts)h(in)m(to)g(the) f(\014le.)0 2311 y(Keyw)m(ord)37 b(and)f(column)f(data)j(are)f (referenced)g(b)m(y)g(name.)60 b(An)m(y)37 b(string)e(of)i(c)m (haracters)i(not)e(surrounded)d(b)m(y)0 2424 y(quotes)41 b(\(ie,)i(a)e(constan)m(t)h(string\))e(or)g(follo)m(w)m(ed)g(b)m(y)h (an)f(op)s(en)g(paren)m(theses)h(\(ie,)i(a)e(function)e(name\))i(will)d (b)s(e)0 2537 y(initially)33 b(in)m(terpreted)i(as)i(a)g(column)e(name) h(and)g(its)g(con)m(ten)m(ts)i(for)e(the)h(curren)m(t)f(ro)m(w)g (inserted)f(in)m(to)i(the)f(ex-)0 2650 y(pression.)j(If)28 b(no)h(suc)m(h)g(column)f(exists,)h(a)h(k)m(eyw)m(ord)f(of)h(that)f (name)g(will)e(b)s(e)h(searc)m(hed)i(for)f(and)f(its)h(v)-5 b(alue)28 b(used,)0 2763 y(if)35 b(found.)55 b(T)-8 b(o)36 b(force)g(the)g(name)g(to)h(b)s(e)e(in)m(terpreted)g(as)h(a)g(k)m(eyw)m (ord)g(\(in)f(case)h(there)g(is)f(b)s(oth)g(a)h(column)f(and)0 2875 y(k)m(eyw)m(ord)41 b(with)d(the)j(same)f(name\),)j(precede)d(the)h (k)m(eyw)m(ord)f(name)g(with)f(a)i(single)d(p)s(ound)g(sign,)k('#',)h (as)d(in)0 2988 y('#NAXIS2'.)g(Due)27 b(to)g(the)f(generalities)g(of)g (FITS)g(column)f(and)h(k)m(eyw)m(ord)h(names,)g(if)e(the)i(column)e(or) h(k)m(eyw)m(ord)0 3101 y(name)34 b(con)m(tains)g(a)g(space)h(or)e(a)i (c)m(haracter)g(whic)m(h)e(migh)m(t)g(app)s(ear)g(as)i(an)e(arithmetic) g(term)h(then)g(inclose)f(the)0 3214 y(name)d(in)f('$')j(c)m(haracters) g(as)e(in)f($MAX)j(PHA$)f(or)f(#$MAX-PHA$.)43 b(Names)31 b(are)f(case)i(insensitiv)m(e.)0 3374 y(T)-8 b(o)32 b(access)g(a)g (table)f(en)m(try)h(in)e(a)i(ro)m(w)f(other)h(than)f(the)g(curren)m(t)g (one,)h(follo)m(w)f(the)g(column's)g(name)g(with)f(a)i(ro)m(w)0 3487 y(o\013set)37 b(within)c(curly)h(braces.)57 b(F)-8 b(or)36 b(example,)h('PHA)p Fc(f)p Fj(-3)p Fc(g)p Fj(')h(will)33 b(ev)-5 b(aluate)37 b(to)f(the)g(v)-5 b(alue)35 b(of)h(column)e(PHA,)j (3)0 3600 y(ro)m(ws)28 b(ab)s(o)m(v)m(e)i(the)e(ro)m(w)h(curren)m(tly)e (b)s(eing)g(pro)s(cessed.)40 b(One)28 b(cannot)h(sp)s(ecify)e(an)h (absolute)g(ro)m(w)g(n)m(um)m(b)s(er,)g(only)g(a)0 3713 y(relativ)m(e)i(o\013set.)42 b(Ro)m(ws)31 b(that)g(fall)e(outside)h (the)g(table)g(will)e(b)s(e)i(treated)h(as)g(unde\014ned,)d(or)j (NULLs.)0 3873 y(Bo)s(olean)g(op)s(erators)g(can)g(b)s(e)f(used)f(in)h (the)g(expression)g(in)f(either)h(their)g(F)-8 b(ortran)31 b(or)f(C)h(forms.)40 b(The)30 b(follo)m(wing)0 3986 y(b)s(o)s(olean)f (op)s(erators)i(are)g(a)m(v)-5 b(ailable:)191 4262 y Fe("equal")428 b(.eq.)46 b(.EQ.)h(==)95 b("not)46 b(equal")476 b(.ne.)94 b(.NE.)h(!=)191 4375 y("less)46 b(than")238 b(.lt.)46 b(.LT.)h(<)143 b("less)46 b(than/equal")188 b(.le.)94 b(.LE.)h(<=)47 b(=<)191 4488 y("greater)e(than")95 b(.gt.)46 b(.GT.)h(>)143 b("greater)45 b(than/equal")g(.ge.)94 b(.GE.)h(>=)47 b(=>)191 4601 y("or")572 b(.or.)46 b(.OR.)h(||)95 b("and")762 b(.and.)46 b(.AND.)h(&&)191 4713 y("negation")236 b(.not.)46 b(.NOT.)h(!)95 b("approx.)45 b(equal\(1e-7\)")92 b(~)0 4989 y Fj(Note)32 b(that)g(the)f(exclamation)g(p)s(oin)m(t,)f(') 10 b(!',)33 b(is)d(a)h(sp)s(ecial)e(UNIX)j(c)m(haracter,)h(so)e(if)f (it)g(is)g(used)g(on)h(the)g(command)0 5102 y(line)g(rather)h(than)h (en)m(tered)g(at)g(a)g(task)g(prompt,)g(it)f(m)m(ust)g(b)s(e)g (preceded)h(b)m(y)f(a)h(bac)m(kslash)f(to)i(force)f(the)g(UNIX)0 5215 y(shell)c(to)i(ignore)f(it.)0 5375 y(The)i(expression)f(ma)m(y)j (also)e(include)e(arithmetic)i(op)s(erators)h(and)f(functions.)46 b(T)-8 b(rigonometric)32 b(functions)f(use)0 5488 y(radians,)22 b(not)h(degrees.)38 b(The)22 b(follo)m(wing)e(arithmetic)h(op)s (erators)i(and)e(functions)f(can)j(b)s(e)e(used)g(in)g(the)h (expression)0 5601 y(\(function)37 b(names)g(are)h(case)g(insensitiv)m (e\).)61 b(A)37 b(n)m(ull)f(v)-5 b(alue)37 b(will)d(b)s(e)j(returned)g (in)f(case)i(of)g(illegal)e(op)s(erations)0 5714 y(suc)m(h)30 b(as)h(divide)d(b)m(y)i(zero,)i(sqrt\(negativ)m(e\))g(log\(negativ)m (e\),)g(log10\(negativ)m(e\),)i(arccos\(.gt.)43 b(1\),)32 b(arcsin\(.gt.)41 b(1\).)p eop %%Page: 120 128 120 127 bop 0 299 a Fj(120)1528 b Fh(CHAPTER)29 b(10.)113 b(EXTENDED)30 b(FILE)h(NAME)f(SYNT)-8 b(AX)191 555 y Fe("addition")474 b(+)j("subtraction")d(-)191 668 y("multiplication") 186 b(*)477 b("division")618 b(/)191 781 y("negation")474 b(-)j("exponentiation")330 b(**)143 b(^)191 894 y("absolute)45 b(value")189 b(abs\(x\))237 b("cosine")762 b(cos\(x\))191 1007 y("sine")666 b(sin\(x\))237 b("tangent")714 b(tan\(x\))191 1120 y("arc)47 b(cosine")379 b(arccos\(x\))93 b("arc)47 b(sine")667 b(arcsin\(x\))191 1233 y("arc)47 b(tangent")331 b(arctan\(x\))93 b("arc)47 b(tangent")523 b(arctan2\(x,y\))191 1346 y("hyperbolic)45 b(cos")189 b(cosh\(x\))g("hyperbolic)45 b(sin")381 b(sinh\(x\))191 1458 y("hyperbolic)45 b(tan")189 b(tanh\(x\))g("round)47 b(to)g(nearest)f(int")94 b(round\(x\))191 1571 y("round)46 b(down)h(to)g(int")f(floor\(x\))141 b("round)47 b(up)g(to)g(int")333 b(ceil\(x\))191 1684 y("exponential")d(exp\(x\))237 b("square)46 b(root")524 b(sqrt\(x\))191 1797 y("natural)45 b(log")333 b(log\(x\))237 b("common)46 b(log")572 b(log10\(x\))191 1910 y("modulus")522 b(i)48 b(\045)f(j)286 b("random)46 b(#)i([0.0,1.0\)")188 b(random\(\))191 2023 y("minimum")522 b(min\(x,y\))141 b("maximum")714 b(max\(x,y\))191 2136 y("cumulative)45 b(sum")189 b(accum\(x\))141 b("sequential)45 b(difference")g (seqdiff\(x\))191 2249 y("if-then-else")282 b(b?x:y)0 2484 y Fj(An)31 b(alternate)h(syn)m(tax)g(for)f(the)g(min)f(and)h(max)g (functions)f(has)h(only)f(a)i(single)e(argumen)m(t)i(whic)m(h)e(should) f(b)s(e)i(a)0 2597 y(v)m(ector)g(v)-5 b(alue)29 b(\(see)h(b)s(elo)m (w\).)40 b(The)29 b(result)f(will)f(b)s(e)h(the)i(minim)m(um/maxim)m (um)c(elemen)m(t)j(con)m(tained)h(within)d(the)0 2710 y(v)m(ector.)0 2870 y(The)35 b(accum\(x\))i(function)e(forms)g(the)h (cum)m(ulativ)m(e)g(sum)f(of)h(x,)h(elemen)m(t)g(b)m(y)f(elemen)m(t.)57 b(V)-8 b(ector)38 b(columns)d(are)0 2983 y(supp)s(orted)i(simply)f(b)m (y)i(p)s(erforming)e(the)j(summation)f(pro)s(cess)g(through)f(all)h (the)h(v)-5 b(alues.)64 b(Null)37 b(v)-5 b(alues)38 b(are)0 3096 y(treated)30 b(as)f(0.)41 b(The)29 b(seqdi\013\(x\))g(function)e (forms)i(the)g(sequen)m(tial)g(di\013erence)f(of)i(x,)f(elemen)m(t)h(b) m(y)f(elemen)m(t.)40 b(The)0 3209 y(\014rst)c(v)-5 b(alue)37 b(of)g(seqdi\013)f(is)g(the)h(\014rst)g(v)-5 b(alue)36 b(of)h(x.)61 b(A)37 b(single)f(n)m(ull)f(v)-5 b(alue)37 b(in)e(x)i(causes)h(a)f(pair)f(of)h(n)m(ulls)e(in)h(the)0 3322 y(output.)55 b(The)35 b(seqdi\013)f(and)h(accum)g(functions)f(are) i(functional)d(in)m(v)m(erses,)k(i.e.,)g(seqdi\013\(accum\(x\)\))f(==)f (x)g(as)0 3435 y(long)30 b(as)h(no)f(n)m(ull)e(v)-5 b(alues)30 b(are)h(presen)m(t.)0 3595 y(The)38 b(follo)m(wing)f(t)m(yp)s(e)i (casting)g(op)s(erators)g(are)g(a)m(v)-5 b(ailable,)41 b(where)d(the)h(inclosing)e(paren)m(theses)i(are)g(required)0 3708 y(and)30 b(tak)m(en)h(from)f(the)h(C)f(language)g(usage.)42 b(Also,)30 b(the)h(in)m(teger)f(to)i(real)e(casts)h(v)-5 b(alues)29 b(to)j(double)d(precision:)764 3944 y Fe("real)46 b(to)h(integer")189 b(\(int\))46 b(x)239 b(\(INT\))46 b(x)764 4057 y("integer)f(to)i(real")190 b(\(float\))46 b(i)143 b(\(FLOAT\))45 b(i)0 4292 y Fj(In)30 b(addition,)e(sev)m(eral)j (constan)m(ts)h(are)f(built)d(in)h(for)h(use)g(in)f(n)m(umerical)g (expressions:)382 4528 y Fe(#pi)667 b(3.1415...)284 b(#e)620 b(2.7182...)382 4641 y(#deg)f(#pi/180)380 b(#row)524 b(current)46 b(row)h(number)382 4754 y(#null)428 b(undefined)45 b(value)142 b(#snull)428 b(undefined)45 b(string)0 4989 y Fj(A)40 b(string)e(constan)m(t)j(m)m(ust)e(b)s(e)g(enclosed)g(in)g (quotes)h(as)f(in)g('Crab'.)67 b(The)39 b("n)m(ull")g(constan)m(ts)h (are)g(useful)e(for)0 5102 y(conditionally)d(setting)j(table)g(v)-5 b(alues)37 b(to)h(a)g(NULL,)g(or)g(unde\014ned,)f(v)-5 b(alue)38 b(\(eg.,)j("col1==-99)e(?)62 b(#NULL)38 b(:)0 5215 y(col1"\).)0 5375 y(There)27 b(is)f(also)i(a)f(function)f(for)i (testing)f(if)f(t)m(w)m(o)j(v)-5 b(alues)27 b(are)h(close)f(to)i(eac)m (h)f(other,)h(i.e.,)f(if)e(they)i(are)g("near")g(eac)m(h)0 5488 y(other)c(to)h(within)c(a)j(user)g(sp)s(eci\014ed)e(tolerance.)39 b(The)24 b(argumen)m(ts,)h(v)-5 b(alue)p 2503 5488 28 4 v 33 w(1)24 b(and)f(v)-5 b(alue)p 2980 5488 V 32 w(2)25 b(can)f(b)s(e)f(in)m(teger)h(or)g(real)0 5601 y(and)32 b(represen)m(t)h(the)g(t)m(w)m(o)h(v)-5 b(alues)32 b(who's)g(pro)m (ximit)m(y)g(is)g(b)s(eing)f(tested)i(to)h(b)s(e)e(within)e(the)j(sp)s (eci\014ed)e(tolerance,)0 5714 y(also)f(an)h(in)m(teger)f(or)h(real:)p eop %%Page: 121 129 121 128 bop 0 299 a Fh(10.10.)73 b(R)m(O)m(W)31 b(FIL)-8 b(TERING)31 b(SPECIFICA)-8 b(TION)1936 b Fj(121)955 555 y Fe(near\(value_1,)44 b(value_2,)h(tolerance\))0 781 y Fj(When)24 b(a)i(NULL,)e(or)h(unde\014ned,)f(v)-5 b(alue)24 b(is)g(encoun)m(tered)h(in)f(the)g(FITS)g(table,)i(the)f(expression)f (will)e(ev)-5 b(aluate)25 b(to)0 894 y(NULL)31 b(unless)e(the)i (unde\014ned)e(v)-5 b(alue)30 b(is)g(not)h(actually)f(required)f(for)i (ev)-5 b(aluation,)31 b(e.g.)43 b("TR)m(UE)31 b(.or.)43 b(NULL")0 1006 y(ev)-5 b(aluates)31 b(to)g(TR)m(UE.)g(The)f(follo)m (wing)e(t)m(w)m(o)k(functions)d(allo)m(w)h(some)h(NULL)f(detection)h (and)f(handling:)430 1232 y Fe("a)47 b(null)f(value?")667 b(ISNULL\(x\))430 1345 y("define)45 b(a)j(value)e(for)h(null")190 b(DEFNULL\(x,y\))0 1570 y Fj(The)36 b(former)h(returns)e(a)i(b)s(o)s (olean)f(v)-5 b(alue)36 b(of)h(TR)m(UE)g(if)f(the)h(argumen)m(t)g(x)g (is)f(NULL.)h(The)f(later)h("de\014nes")g(a)0 1683 y(v)-5 b(alue)34 b(to)h(b)s(e)e(substituted)g(for)h(NULL)g(v)-5 b(alues;)36 b(it)e(returns)f(the)h(v)-5 b(alue)34 b(of)g(x)g(if)f(x)i (is)e(not)h(NULL,)h(otherwise)e(it)0 1796 y(returns)c(the)i(v)-5 b(alue)30 b(of)g(y)-8 b(.)0 2081 y Fd(10.10.2)113 b(Bit)35 b(Masks)0 2300 y Fj(Bit)g(masks)g(can)h(b)s(e)f(used)f(to)i(select)g (out)f(ro)m(ws)h(from)e(bit)h(columns)f(\(TF)m(ORMn)h(=)g(#X\))h(in)e (FITS)g(\014les.)54 b(T)-8 b(o)0 2413 y(represen)m(t)30 b(the)h(mask,)g(binary)-8 b(,)29 b(o)s(ctal,)i(and)f(hex)g(formats)g (are)h(allo)m(w)m(ed:)811 2638 y Fe(binary:)142 b (b0110xx1010000101xxxx00)o(01)811 2751 y(octal:)190 b(o720x1)46 b(->)h(\(b111010000xxx001\))811 2864 y(hex:)286 b(h0FxD)94 b(->)47 b(\(b00001111xxxx1101\))0 3090 y Fj(In)22 b(all)g(the)h (represen)m(tations,)i(an)d(x)h(or)g(X)g(is)f(allo)m(w)m(ed)h(in)e(the) i(mask)g(as)g(a)h(wild)c(card.)38 b(Note)25 b(that)e(the)g(x)g (represen)m(ts)0 3203 y(a)k(di\013eren)m(t)g(n)m(um)m(b)s(er)f(of)h (wild)d(card)j(bits)f(in)g(eac)m(h)i(represen)m(tation.)40 b(All)25 b(represen)m(tations)i(are)h(case)g(insensitiv)m(e.)0 3363 y(T)-8 b(o)28 b(construct)g(the)g(b)s(o)s(olean)e(expression)h (using)f(the)i(mask)f(as)h(the)g(b)s(o)s(olean)e(equal)h(op)s(erator)h (describ)s(ed)e(ab)s(o)m(v)m(e)0 3476 y(on)34 b(a)h(bit)f(table)h (column.)52 b(F)-8 b(or)35 b(example,)h(if)d(y)m(ou)i(had)f(a)h(7)g (bit)f(column)f(named)h(\015ags)h(in)e(a)i(FITS)f(table)h(and)0 3589 y(w)m(an)m(ted)c(all)e(ro)m(ws)i(ha)m(ving)f(the)g(bit)g(pattern)g (0010011,)k(the)c(selection)h(expression)e(w)m(ould)g(b)s(e:)1336 3814 y Fe(flags)47 b(==)g(b0010011)191 3927 y(or)1336 4040 y(flags)g(.eq.)f(b10011)0 4265 y Fj(It)35 b(is)f(also)h(p)s (ossible)d(to)k(test)g(if)e(a)h(range)g(of)g(bits)f(is)g(less)g(than,)i (less)e(than)h(equal,)h(greater)g(than)e(and)h(greater)0 4378 y(than)30 b(equal)g(to)h(a)g(particular)e(b)s(o)s(olean)g(v)-5 b(alue:)1336 4604 y Fe(flags)47 b(<=)g(bxxx010xx)1336 4717 y(flags)g(.gt.)f(bxxx100xx)1336 4829 y(flags)h(.le.)f(b1xxxxxxx)0 5055 y Fj(Notice)31 b(the)g(use)f(of)h(the)f(x)g(bit)g(v)-5 b(alue)30 b(to)h(limit)d(the)i(range)h(of)g(bits)e(b)s(eing)g (compared.)0 5215 y(It)j(is)g(not)g(necessary)h(to)g(sp)s(ecify)e(the)i (leading)e(\(most)i(signi\014can)m(t\))f(zero)h(\(0\))g(bits)e(in)g (the)i(mask,)g(as)g(sho)m(wn)e(in)0 5328 y(the)g(second)f(expression)f (ab)s(o)m(v)m(e.)0 5488 y(Bit)43 b(wise)f(AND,)i(OR)e(and)g(NOT)h(op)s (erations)f(are)h(also)g(p)s(ossible)d(on)j(t)m(w)m(o)h(or)f(more)g (bit)f(\014elds)f(using)h(the)0 5601 y('&'\(AND\),)35 b(')p Fc(j)p Fj('\(OR\),)g(and)e(the)h(')10 b(!'\(NOT\))34 b(op)s(erators.)51 b(All)32 b(of)h(these)h(op)s(erators)g(result)e(in)h (a)h(bit)e(\014eld)g(whic)m(h)0 5714 y(can)f(then)f(b)s(e)f(used)h (with)f(the)i(equal)f(op)s(erator.)41 b(F)-8 b(or)31 b(example:)p eop %%Page: 122 130 122 129 bop 0 299 a Fj(122)1528 b Fh(CHAPTER)29 b(10.)113 b(EXTENDED)30 b(FILE)h(NAME)f(SYNT)-8 b(AX)1241 555 y Fe(\(!flags\))45 b(==)j(b1101100)1241 668 y(\(flags)e(&)h(b1000001\))f (==)h(bx000001)0 928 y Fj(Bit)34 b(\014elds)f(can)h(b)s(e)f(app)s (ended)g(as)h(w)m(ell)f(using)g(the)h('+')g(op)s(erator.)53 b(Strings)32 b(can)j(b)s(e)e(concatenated)j(this)d(w)m(a)m(y)-8 b(,)0 1041 y(to)s(o.)0 1331 y Fd(10.10.3)113 b(V)-9 b(ector)36 b(Columns)0 1550 y Fj(V)-8 b(ector)37 b(columns)d(can)i(also)f(b)s(e)g (used)f(in)g(building)e(the)j(expression.)55 b(No)36 b(sp)s(ecial)e(syn)m(tax)h(is)g(required)e(if)i(one)0 1663 y(w)m(an)m(ts)46 b(to)f(op)s(erate)h(on)f(all)f(elemen)m(ts)h(of)g (the)h(v)m(ector.)86 b(Simply)42 b(use)j(the)g(column)f(name)h(as)g (for)g(a)g(scalar)0 1776 y(column.)c(V)-8 b(ector)32 b(columns)e(can)h(b)s(e)f(freely)g(in)m(termixed)g(with)f(scalar)i (columns)e(or)i(constan)m(ts)h(in)e(virtually)e(all)0 1889 y(expressions.)39 b(The)29 b(result)f(will)e(b)s(e)j(of)g(the)g (same)h(dimension)c(as)k(the)f(v)m(ector.)42 b(Tw)m(o)29 b(v)m(ectors)i(in)d(an)h(expression,)0 2002 y(though,)f(need)e(to)i(ha) m(v)m(e)g(the)f(same)g(n)m(um)m(b)s(er)f(of)h(elemen)m(ts)g(and)f(ha)m (v)m(e)j(the)e(same)g(dimensions.)37 b(The)26 b(only)g(places)0 2115 y(a)35 b(v)m(ector)h(column)d(cannot)i(b)s(e)f(used)f(\(for)i(no)m (w,)g(an)m(yw)m(a)m(y\))h(are)f(the)g(SA)m(O)f(region)g(functions)f (and)g(the)i(NEAR)0 2228 y(b)s(o)s(olean)29 b(function.)0 2388 y(Arithmetic)22 b(and)g(logical)h(op)s(erations)f(are)i(all)e(p)s (erformed)f(on)i(an)g(elemen)m(t)g(b)m(y)g(elemen)m(t)h(basis.)37 b(Comparing)22 b(t)m(w)m(o)0 2501 y(v)m(ector)32 b(columns,)d(eg)i ("COL1)f(==)g(COL2",)g(th)m(us)g(results)f(in)g(another)h(v)m(ector)i (of)e(b)s(o)s(olean)g(v)-5 b(alues)29 b(indicating)0 2614 y(whic)m(h)g(elemen)m(ts)i(of)f(the)h(t)m(w)m(o)h(v)m(ectors)f (are)g(equal.)0 2774 y(Eigh)m(t)f(functions)f(are)i(a)m(v)-5 b(ailable)30 b(that)h(op)s(erate)g(on)f(a)h(v)m(ector)h(and)d(return)h (a)g(scalar)h(result:)191 3034 y Fe("minimum")284 b(MIN\(V\))475 b("maximum")714 b(MAX\(V\))191 3147 y("average")284 b(AVERAGE\(V\))f ("median")762 b(MEDIAN\(V\))191 3259 y("sumation")236 b(SUM\(V\))475 b("standard)46 b(deviation")188 b(STDDEV\(V\))191 3372 y("#)47 b(of)g(values")94 b(NELEM\(V\))379 b("#)48 b(of)f(non-null)e(values")94 b(NVALID\(V\))0 3632 y Fj(where)40 b(V)h(represen)m(ts)g(the)g(name)g(of)h(a)f(v)m(ector)h(column)e(or)h (a)h(man)m(ually)d(constructed)i(v)m(ector)i(using)c(curly)0 3745 y(brac)m(k)m(ets)27 b(as)f(describ)s(ed)d(b)s(elo)m(w.)38 b(The)25 b(\014rst)g(6)h(of)g(these)g(functions)e(ignore)h(an)m(y)h(n)m (ull)d(v)-5 b(alues)25 b(in)f(the)i(v)m(ector)h(when)0 3858 y(computing)i(the)i(result.)0 4018 y(The)g(SUM)h(function)e (literally)g(sums)h(all)f(the)i(elemen)m(ts)g(in)f(x,)h(returning)e(a)i (scalar)g(v)-5 b(alue.)44 b(If)31 b(V)h(is)f(a)h(b)s(o)s(olean)0 4131 y(v)m(ector,)40 b(SUM)c(returns)f(the)h(n)m(um)m(b)s(er)f(of)i(TR) m(UE)f(elemen)m(ts.)59 b(The)36 b(NELEM)g(function)f(returns)g(the)h(n) m(um)m(b)s(er)0 4244 y(of)h(elemen)m(ts)f(in)g(v)m(ector)i(V)e(whereas) h(NV)-10 b(ALID)36 b(return)g(the)h(n)m(um)m(b)s(er)e(of)h(non-n)m(ull) e(elemen)m(ts)j(in)e(the)i(v)m(ector.)0 4357 y(\(NELEM)28 b(also)g(op)s(erates)g(on)g(bit)e(and)h(string)g(columns,)g(returning)f (their)h(column)f(widths.\))39 b(As)27 b(an)h(example,)0 4470 y(to)42 b(test)g(whether)f(all)f(elemen)m(ts)i(of)g(t)m(w)m(o)g(v) m(ectors)h(satisfy)e(a)h(giv)m(en)f(logical)g(comparison,)i(one)f(can)g (use)f(the)0 4583 y(expression)668 4842 y Fe(SUM\()47 b(COL1)f(>)i(COL2)f(\))g(==)g(NELEM\()f(COL1)h(\))0 5102 y Fj(whic)m(h)31 b(will)e(return)i(TR)m(UE)h(if)f(all)g(elemen)m(ts)h (of)g(COL1)g(are)g(greater)h(than)f(their)f(corresp)s(onding)f(elemen)m (ts)i(in)0 5215 y(COL2.)0 5375 y(T)-8 b(o)32 b(sp)s(ecify)e(a)j(single) d(elemen)m(t)i(of)g(a)g(v)m(ector,)i(giv)m(e)e(the)g(column)e(name)i (follo)m(w)m(ed)f(b)m(y)h(a)g(comma-separated)h(list)0 5488 y(of)c(co)s(ordinates)f(enclosed)h(in)e(square)i(brac)m(k)m(ets.) 41 b(F)-8 b(or)30 b(example,)f(if)e(a)i(v)m(ector)i(column)c(named)i (PHAS)f(exists)g(in)0 5601 y(the)f(table)f(as)h(a)g(one)g(dimensional,) e(256)j(comp)s(onen)m(t)f(list)e(of)i(n)m(um)m(b)s(ers)e(from)h(whic)m (h)g(y)m(ou)h(w)m(an)m(ted)g(to)g(select)h(the)0 5714 y(57th)k(comp)s(onen)m(t)g(for)f(use)g(in)f(the)i(expression,)e(then)i (PHAS[57])g(w)m(ould)e(do)i(the)f(tric)m(k.)44 b(Higher)31 b(dimensional)p eop %%Page: 123 131 123 130 bop 0 299 a Fh(10.10.)73 b(R)m(O)m(W)31 b(FIL)-8 b(TERING)31 b(SPECIFICA)-8 b(TION)1936 b Fj(123)0 555 y(arra)m(ys)41 b(of)h(data)f(ma)m(y)h(app)s(ear)f(in)e(a)j(column.)72 b(But)41 b(in)f(order)g(to)i(in)m(terpret)e(them,)k(the)e(TDIMn)e(k)m (eyw)m(ord)0 668 y(m)m(ust)34 b(app)s(ear)g(in)f(the)h(header.)52 b(Assuming)33 b(that)i(a)f(\(4,4,4,4\))k(arra)m(y)c(is)g(pac)m(k)m(ed)h (in)m(to)f(eac)m(h)i(ro)m(w)e(of)g(a)h(column)0 781 y(named)26 b(ARRA)-8 b(Y4D,)28 b(the)f(\(1,2,3,4\))i(comp)s(onen)m(t)e(elemen)m(t) f(of)h(eac)m(h)g(ro)m(w)g(is)e(accessed)j(b)m(y)e(ARRA)-8 b(Y4D[1,2,3,4].)0 894 y(Arra)m(ys)33 b(up)e(to)j(dimension)c(5)j(are)f (curren)m(tly)g(supp)s(orted.)46 b(Eac)m(h)33 b(v)m(ector)h(index)d (can)i(itself)e(b)s(e)h(an)h(expression,)0 1007 y(although)38 b(it)g(m)m(ust)h(ev)-5 b(aluate)39 b(to)g(an)g(in)m(teger)g(v)-5 b(alue)38 b(within)e(the)j(b)s(ounds)d(of)j(the)g(v)m(ector.)67 b(V)-8 b(ector)40 b(columns)0 1120 y(whic)m(h)30 b(con)m(tain)h(spaces) h(or)f(arithmetic)f(op)s(erators)i(m)m(ust)f(ha)m(v)m(e)h(their)e (names)h(enclosed)g(in)f("$")i(c)m(haracters)h(as)0 1233 y(with)c($ARRA)-8 b(Y-4D$[1,2,3,4].)0 1393 y(A)45 b(more)f(C-lik)m(e)g (syn)m(tax)i(for)e(sp)s(ecifying)e(v)m(ector)47 b(indices)42 b(is)i(also)h(a)m(v)-5 b(ailable.)82 b(The)45 b(elemen)m(t)g(used)e(in) h(the)0 1506 y(preceding)27 b(example)h(alternativ)m(ely)g(could)f(b)s (e)h(sp)s(eci\014ed)f(with)f(the)j(syn)m(tax)g(ARRA)-8 b(Y4D[4][3][2][1].)45 b(Note)30 b(the)0 1619 y(rev)m(erse)40 b(order)f(of)h(indices)d(\(as)j(in)e(C\),)i(as)f(w)m(ell)g(as)g(the)h (fact)g(that)g(the)g(v)-5 b(alues)39 b(are)g(still)f(ones-based)h(\(as) h(in)0 1732 y(F)-8 b(ortran)39 b({)g(adopted)g(to)g(a)m(v)m(oid)g(am)m (biguit)m(y)f(for)h(1D)g(v)m(ectors\).)67 b(With)38 b(this)g(syn)m (tax,)j(one)e(do)s(es)f(not)h(need)f(to)0 1844 y(sp)s(ecify)29 b(all)g(of)i(the)f(indices.)39 b(T)-8 b(o)31 b(extract)h(a)f(3D)g (slice)e(of)i(this)e(4D)i(arra)m(y)-8 b(,)32 b(use)e(ARRA)-8 b(Y4D[4].)0 2005 y(V)g(ariable-length)30 b(v)m(ector)i(columns)d(are)h (not)h(supp)s(orted.)0 2165 y(V)-8 b(ectors)24 b(can)e(b)s(e)f(man)m (ually)f(constructed)j(within)c(the)j(expression)f(using)f(a)i (comma-separated)i(list)d(of)h(elemen)m(ts)0 2278 y(surrounded)35 b(b)m(y)j(curly)f(braces)i(\(')p Fc(fg)p Fj('\).)66 b(F)-8 b(or)38 b(example,)i(')p Fc(f)p Fj(1,3,6,1)p Fc(g)p Fj(')i(is)c(a)g (4-elemen)m(t)h(v)m(ector)h(con)m(taining)e(the)0 2391 y(v)-5 b(alues)25 b(1,)i(3,)g(6,)g(and)e(1.)40 b(The)25 b(v)m(ector)i(can)f(con)m(tain)g(only)f(b)s(o)s(olean,)g(in)m(teger,)j (and)d(real)g(v)-5 b(alues)25 b(\(or)h(expressions\).)0 2503 y(The)c(elemen)m(ts)h(will)d(b)s(e)i(promoted)h(to)g(the)g (highest)f(data)h(t)m(yp)s(e)g(presen)m(t.)38 b(An)m(y)22 b(elemen)m(ts)h(whic)m(h)f(are)h(themselv)m(es)0 2616 y(v)m(ectors,)40 b(will)34 b(b)s(e)i(expanded)g(out)h(with)f(eac)m(h)h (of)g(its)f(elemen)m(ts)i(b)s(ecoming)d(an)i(elemen)m(t)g(in)f(the)h (constructed)0 2729 y(v)m(ector.)0 3032 y Fd(10.10.4)113 b(Go)s(o)s(d)38 b(Time)e(In)m(terv)-6 b(al)36 b(Filtering)0 3254 y Fj(A)44 b(common)g(\014ltering)f(metho)s(d)g(in)m(v)m(olv)m(es)h (selecting)g(ro)m(ws)g(whic)m(h)e(ha)m(v)m(e)k(a)e(time)g(v)-5 b(alue)43 b(whic)m(h)g(lies)f(within)0 3367 y(what)37 b(is)f(called)h(a)h(Go)s(o)s(d)f(Time)f(In)m(terv)-5 b(al)37 b(or)g(GTI.)g(The)g(time)g(in)m(terv)-5 b(als)36 b(are)i(de\014ned)e(in)g(a)h(separate)i(FITS)0 3480 y(table)h (extension)g(whic)m(h)e(con)m(tains)i(2)h(columns)e(giving)f(the)j (start)f(and)g(stop)g(time)f(of)h(eac)m(h)i(go)s(o)s(d)e(in)m(terv)-5 b(al.)0 3592 y(The)34 b(\014ltering)f(op)s(eration)i(accepts)h(only)d (those)j(ro)m(ws)e(of)h(the)g(input)e(table)i(whic)m(h)e(ha)m(v)m(e)j (an)f(asso)s(ciated)g(time)0 3705 y(whic)m(h)f(falls)h(within)e(one)j (of)g(the)g(time)f(in)m(terv)-5 b(als)35 b(de\014ned)g(in)f(the)i(GTI)g (extension.)56 b(A)36 b(high)f(lev)m(el)g(function,)0 3818 y(gti\014lter\(a,b,c,d\),)42 b(is)d(a)m(v)-5 b(ailable)39 b(whic)m(h)f(ev)-5 b(aluates)40 b(eac)m(h)h(ro)m(w)e(of)h(the)f(input)f (table)h(and)g(returns)f(TR)m(UE)i(or)0 3931 y(F)-10 b(ALSE)30 b(dep)s(ending)e(whether)i(the)g(ro)m(w)h(is)e(inside)f(or)i (outside)g(the)h(go)s(o)s(d)f(time)g(in)m(terv)-5 b(al.)40 b(The)30 b(syn)m(tax)h(is)286 4202 y Fe(gtifilter\()45 b([)j("gtifile")d([,)i(expr)g([,)g("STARTCOL",)e("STOPCOL")g(])j(])f(]) g(\))191 4314 y(or)286 4427 y(gtifilter\()e([)j('gtifile')d([,)i(expr)g ([,)g('STARTCOL',)e('STOPCOL')g(])j(])f(])g(\))0 4698 y Fj(where)20 b(eac)m(h)h("[]")h(demarks)e(optional)f(parameters.)38 b(Note)21 b(that)g(the)g(quotes)f(around)g(the)g(gti\014le)g(and)f(ST) -8 b(AR)g(T/STOP)0 4811 y(column)32 b(are)i(required.)49 b(Either)33 b(single)f(or)i(double)e(quotes)i(ma)m(y)g(b)s(e)f(used.)50 b(In)33 b(cases)h(where)g(this)e(expression)0 4924 y(is)d(en)m(tered)h (on)g(the)g(Unix)f(command)h(line,)e(enclose)i(the)g(en)m(tire)g (expression)f(in)f(double)h(quotes,)h(and)g(then)f(use)0 5036 y(single)23 b(quotes)i(within)c(the)k(expression)e(to)i(enclose)f (the)h('gti\014le')f(and)f(other)i(terms.)38 b(It)25 b(is)e(also)h(usually)e(p)s(ossible)0 5149 y(to)38 b(do)e(the)h(rev)m (erse,)j(and)c(enclose)h(the)g(whole)f(expression)g(in)f(single)h (quotes)h(and)f(then)h(use)f(double)f(quotes)0 5262 y(within)c(the)i (expression.)49 b(The)33 b(gti\014le,)g(if)g(sp)s(eci\014ed,)f(can)i(b) s(e)f(blank)f(\(""\))j(whic)m(h)d(will)e(mean)k(to)g(use)f(the)h (\014rst)0 5375 y(extension)f(with)g(the)g(name)h("*GTI*")h(in)e(the)g (curren)m(t)h(\014le,)g(a)g(plain)d(extension)i(sp)s(eci\014er)f(\(eg,) k("+2",)g("[2]",)0 5488 y(or)30 b("[STDGTI]"\))i(whic)m(h)d(will)f(b)s (e)i(used)f(to)j(select)f(an)f(extension)g(in)f(the)i(curren)m(t)f (\014le,)g(or)g(a)h(regular)f(\014lename)0 5601 y(with)f(or)i(without)e (an)i(extension)f(sp)s(eci\014er)f(whic)m(h)g(in)g(the)i(latter)g(case) g(will)d(mean)i(to)i(use)e(the)h(\014rst)e(extension)0 5714 y(with)36 b(an)h(extension)f(name)i("*GTI*".)62 b(Expr)36 b(can)h(b)s(e)g(an)m(y)g(arithmetic)g(expression,)g (including)d(simply)h(the)p eop %%Page: 124 132 124 131 bop 0 299 a Fj(124)1528 b Fh(CHAPTER)29 b(10.)113 b(EXTENDED)30 b(FILE)h(NAME)f(SYNT)-8 b(AX)0 555 y Fj(time)35 b(column)g(name.)57 b(A)36 b(v)m(ector)h(time)f(expression)e(will)f (pro)s(duce)i(a)h(v)m(ector)h(b)s(o)s(olean)e(result.)56 b(ST)-8 b(AR)g(TCOL)0 668 y(and)27 b(STOPCOL)f(are)i(the)g(names)g(of)g (the)g(ST)-8 b(AR)g(T/STOP)26 b(columns)h(in)f(the)i(GTI)g(extension.) 40 b(If)27 b(one)h(of)g(them)0 781 y(is)h(sp)s(eci\014ed,)g(they)i(b)s (oth)f(m)m(ust)g(b)s(e.)0 941 y(In)21 b(its)g(simplest)f(form,)k(no)d (parameters)h(need)g(to)h(b)s(e)e(pro)m(vided)f({)i(default)f(v)-5 b(alues)21 b(will)f(b)s(e)h(used.)37 b(The)21 b(expression)0 1054 y("gti\014lter\(\)")31 b(is)f(equiv)-5 b(alen)m(t)29 b(to)334 1322 y Fe(gtifilter\()45 b("",)i(TIME,)f("*START*",)f ("*STOP*")h(\))0 1590 y Fj(This)30 b(will)e(searc)m(h)k(the)g(curren)m (t)f(\014le)f(for)h(a)h(GTI)f(extension,)g(\014lter)g(the)g(TIME)g (column)f(in)g(the)i(curren)m(t)f(table,)0 1703 y(using)i(ST)-8 b(AR)g(T/STOP)34 b(times)h(tak)m(en)g(from)g(columns)e(in)h(the)h(GTI)g (extension)f(with)g(names)g(con)m(taining)h(the)0 1816 y(strings)c("ST)-8 b(AR)g(T")33 b(and)e("STOP".)46 b(The)32 b(wildcards)d(\('*'\))34 b(allo)m(w)e(sligh)m(t)f(v)-5 b(ariations)31 b(in)g(naming)g(con)m(v)m(en)m(tions)0 1929 y(suc)m(h)38 b(as)g("TST)-8 b(AR)g(T")39 b(or)f("ST)-8 b(AR)g(TTIME".)65 b(The)37 b(same)i(default)f(v)-5 b(alues)37 b(apply)g(for)h(unsp)s(eci\014ed)e(parame-)0 2042 y(ters)g(when)f(the)h (\014rst)f(one)i(or)f(t)m(w)m(o)h(parameters)f(are)h(sp)s(eci\014ed.)55 b(The)36 b(function)e(automatically)i(searc)m(hes)h(for)0 2154 y(TIMEZER)m(O/I/F)g(k)m(eyw)m(ords)f(in)f(the)i(curren)m(t)f(and)g (GTI)g(extensions,)h(applying)e(a)h(relativ)m(e)h(time)f(o\013set,)j (if)0 2267 y(necessary)-8 b(.)0 2568 y Fd(10.10.5)113 b(Spatial)36 b(Region)h(Filtering)0 2788 y Fj(Another)h(common)g (\014ltering)e(metho)s(d)h(selects)h(ro)m(ws)g(based)g(on)f(whether)h (the)g(spatial)f(p)s(osition)e(asso)s(ciated)0 2901 y(with)c(eac)m(h)j (ro)m(w)e(is)g(lo)s(cated)h(within)d(a)j(giv)m(en)f(2-dimensional)e (region.)47 b(The)32 b(syn)m(tax)h(for)f(this)g(high-lev)m(el)f (\014lter)0 3014 y(is)334 3282 y Fe(regfilter\()45 b("regfilename")f([) k(,)f(Xexpr,)f(Yexpr)h([)g(,)h("wcs)e(cols")h(])g(])g(\))0 3550 y Fj(where)22 b(eac)m(h)i("[]")g(demarks)e(optional)g(parameters.) 38 b(The)22 b(region)g(\014le)g(name)g(is)g(required)f(and)h(m)m(ust)g (b)s(e)g(enclosed)0 3663 y(in)38 b(quotes.)70 b(The)39 b(remaining)f(parameters)i(are)g(optional.)68 b(The)39 b(region)g(\014le)g(is)g(an)g(ASCI)s(I)g(text)h(\014le)f(whic)m(h)0 3776 y(con)m(tains)30 b(a)f(list)f(of)i(one)f(or)h(more)f(geometric)i (shap)s(es)d(\(circle,)i(ellipse,)d(b)s(o)m(x,)j(etc.\))42 b(whic)m(h)28 b(de\014nes)g(a)i(region)f(on)0 3889 y(the)i(celestial)f (sphere)g(or)h(an)g(area)g(within)d(a)j(particular)f(2D)h(image.)42 b(The)30 b(region)h(\014le)f(is)f(t)m(ypically)h(generated)0 4002 y(using)21 b(an)i(image)g(displa)m(y)e(program)i(suc)m(h)f(as)h (fv/PO)m(W)h(\(distribute)c(b)m(y)j(the)g(HEASAR)m(C\),)g(or)g(ds9)g (\(distributed)0 4115 y(b)m(y)k(the)g(Smithsonian)d(Astroph)m(ysical)i (Observ)-5 b(atory\).)39 b(Users)27 b(should)e(refer)h(to)i(the)f(do)s (cumen)m(tation)f(pro)m(vided)0 4228 y(with)j(these)i(programs)f(for)g (more)h(details)e(on)h(the)h(syn)m(tax)g(used)e(in)g(the)i(region)f (\014les.)0 4388 y(In)44 b(its)g(simpliest)e(form,)47 b(\(e.g.,)j(reg\014lter\("region.reg"\))c(\))f(the)g(co)s(ordinates)f (in)f(the)i(default)e('X')i(and)f('Y')0 4501 y(columns)32 b(will)e(b)s(e)i(used)g(to)i(determine)e(if)f(eac)m(h)j(ro)m(w)f(is)f (inside)f(or)i(outside)f(the)h(area)h(sp)s(eci\014ed)d(in)g(the)i (region)0 4613 y(\014le.)40 b(Alternate)31 b(p)s(osition)d(column)h (names,)i(or)f(expressions,)f(ma)m(y)i(b)s(e)f(en)m(tered)h(if)e (needed,)i(as)f(in)382 4881 y Fe(regfilter\("region.reg",)41 b(XPOS,)47 b(YPOS\))0 5149 y Fj(Region)36 b(\014ltering)e(can)i(b)s(e)f (applied)e(most)j(unam)m(biguously)d(if)i(the)h(p)s(ositions)e(in)g (the)i(region)f(\014le)g(and)g(in)g(the)0 5262 y(table)g(to)h(b)s(e)e (\014ltered)g(are)i(b)s(oth)e(giv)m(e)i(in)e(terms)h(of)g(absolute)g (celestial)g(co)s(ordinate)g(units.)53 b(In)35 b(this)f(case)i(the)0 5375 y(lo)s(cations)24 b(and)f(sizes)h(of)h(the)f(geometric)h(shap)s (es)f(in)f(the)h(region)g(\014le)f(are)i(sp)s(eci\014ed)e(in)g(angular) g(units)g(on)h(the)g(sky)0 5488 y(\(e.g.,)32 b(p)s(ositions)c(giv)m(en) j(in)e(R.A.)h(and)g(Dec.)42 b(and)30 b(sizes)g(in)f(arcseconds)h(or)h (arcmin)m(utes\).)40 b(Similarly)-8 b(,)27 b(eac)m(h)32 b(ro)m(w)0 5601 y(of)h(the)h(\014ltered)e(table)h(will)d(ha)m(v)m(e)35 b(a)e(celestial)g(co)s(ordinate)g(asso)s(ciated)g(with)f(it.)49 b(This)31 b(asso)s(ciation)i(is)f(usually)0 5714 y(implemen)m(ted)37 b(using)f(a)j(set)g(of)f(so-called)g('W)-8 b(orld)38 b(Co)s(ordinate)g(System')g(\(or)h(W)m(CS\))f(FITS)g(k)m(eyw)m(ords)g (that)p eop %%Page: 125 133 125 132 bop 0 299 a Fh(10.10.)73 b(R)m(O)m(W)31 b(FIL)-8 b(TERING)31 b(SPECIFICA)-8 b(TION)1936 b Fj(125)0 555 y(de\014ne)27 b(the)g(co)s(ordinate)g(transformation)g(that)h(m)m(ust)f (b)s(e)f(applied)f(to)j(the)g(v)-5 b(alues)26 b(in)g(the)i('X')g(and)e ('Y')i(columns)0 668 y(to)j(calculate)g(the)f(co)s(ordinate.)0 828 y(Alternativ)m(ely)-8 b(,)27 b(one)g(can)g(p)s(erform)e(spatial)h (\014ltering)e(using)h(unitless)g('pixel')g(co)s(ordinates)i(for)f(the) h(regions)f(and)0 941 y(ro)m(w)33 b(p)s(ositions.)47 b(In)33 b(this)f(case)i(the)f(user)g(m)m(ust)g(b)s(e)f(careful)g(to)i (ensure)f(that)g(the)h(p)s(ositions)d(in)h(the)h(2)g(\014les)g(are)0 1054 y(self-consisten)m(t.)52 b(A)34 b(t)m(ypical)g(problem)e(is)h (that)i(the)f(region)g(\014le)f(ma)m(y)i(b)s(e)e(generated)j(using)c(a) j(binned)c(image,)0 1167 y(but)h(the)h(un)m(binned)d(co)s(ordinates)i (are)h(giv)m(en)g(in)e(the)i(ev)m(en)m(t)i(table.)47 b(The)32 b(R)m(OSA)-8 b(T)33 b(ev)m(en)m(ts)h(\014les,)f(for)f (example,)0 1280 y(ha)m(v)m(e)f(X)f(and)f(Y)g(pixel)f(co)s(ordinates)h (that)i(range)f(from)f(1)h(-)g(15360.)42 b(These)30 b(co)s(ordinates)f (are)h(t)m(ypically)e(binned)0 1393 y(b)m(y)33 b(a)h(factor)g(of)f(32)h (to)g(pro)s(duce)e(a)i(480x480)i(pixel)31 b(image.)50 b(If)32 b(one)i(then)f(uses)g(a)g(region)g(\014le)f(generated)i(from)0 1506 y(this)29 b(image)i(\(in)f(image)g(pixel)f(units\))h(to)h (\014lter)e(the)i(R)m(OSA)-8 b(T)30 b(ev)m(en)m(ts)i(\014le,)e(then)g (the)h(X)g(and)f(Y)g(column)g(v)-5 b(alues)0 1619 y(m)m(ust)30 b(b)s(e)g(con)m(v)m(erted)i(to)f(corresp)s(onding)d(pixel)h(units)g(as) h(in:)382 1885 y Fe(regfilter\("rosat.reg",)42 b(X/32.+.5,)j (Y/32.+.5\))0 2151 y Fj(Note)h(that)f(this)e(binning)e(con)m(v)m (ersion)k(is)e(not)i(necessary)g(if)e(the)i(region)f(\014le)f(is)h(sp)s (eci\014ed)e(using)h(celestial)0 2264 y(co)s(ordinate)h(units)f (instead)g(of)h(pixel)f(units)g(b)s(ecause)h(CFITSIO)e(is)i(then)f (able)h(to)h(directly)e(compare)i(the)0 2377 y(celestial)27 b(co)s(ordinate)h(of)f(eac)m(h)i(ro)m(w)f(in)e(the)i(table)f(with)g (the)g(celestial)h(co)s(ordinates)f(in)f(the)i(region)f(\014le)g (without)0 2490 y(ha)m(ving)j(to)h(kno)m(w)f(an)m(ything)g(ab)s(out)g (ho)m(w)h(the)f(image)h(ma)m(y)g(ha)m(v)m(e)g(b)s(een)f(binned.)0 2650 y(The)f(last)g("w)m(cs)h(cols")g(parameter)g(should)d(rarely)h(b)s (e)h(needed.)40 b(If)29 b(supplied,)d(this)j(string)f(con)m(tains)i (the)f(names)0 2763 y(of)37 b(the)g(2)h(columns)e(\(space)i(or)f(comma) g(separated\))h(whic)m(h)e(ha)m(v)m(e)i(the)g(asso)s(ciated)f(W)m(CS)g (k)m(eyw)m(ords.)61 b(If)37 b(not)0 2876 y(supplied,)d(the)i(\014lter)f (will)f(scan)i(the)g(X)g(and)f(Y)h(expressions)f(for)h(column)e(names.) 58 b(If)35 b(only)g(one)i(is)e(found)f(in)0 2989 y(eac)m(h)e (expression,)d(those)i(columns)e(will)f(b)s(e)h(used,)h(otherwise)g(an) g(error)g(will)e(b)s(e)i(returned.)0 3149 y(These)g(region)g(shap)s(es) g(are)g(supp)s(orted)f(\(names)h(are)h(case)h(insensitiv)m(e\):)334 3415 y Fe(Point)428 b(\()48 b(X1,)f(Y1)g(\))715 b(<-)48 b(One)f(pixel)f(square)g(region)334 3528 y(Line)476 b(\()48 b(X1,)f(Y1,)g(X2,)f(Y2)i(\))333 b(<-)48 b(One)f(pixel)f(wide)h(region) 334 3641 y(Polygon)332 b(\()48 b(X1,)f(Y1,)g(X2,)f(Y2,)h(...)g(\))95 b(<-)48 b(Rest)e(are)h(interiors)e(with)334 3754 y(Rectangle)236 b(\()48 b(X1,)f(Y1,)g(X2,)f(Y2,)h(A)h(\))334 b(|)47 b(boundaries)e (considered)334 3867 y(Box)524 b(\()48 b(Xc,)f(Yc,)g(Wdth,)f(Hght,)g(A) i(\))143 b(V)47 b(within)f(the)h(region)334 3980 y(Diamond)332 b(\()48 b(Xc,)f(Yc,)g(Wdth,)f(Hght,)g(A)i(\))334 4093 y(Circle)380 b(\()48 b(Xc,)f(Yc,)g(R)g(\))334 4206 y(Annulus)332 b(\()48 b(Xc,)f(Yc,)g(Rin,)f(Rout)h(\))334 4319 y(Ellipse)332 b(\()48 b(Xc,)f(Yc,)g(Rx,)f(Ry,)h(A)h(\))334 4431 y(Elliptannulus)c(\() k(Xc,)f(Yc,)g(Rinx,)f(Riny,)g(Routx,)g(Routy,)g(Ain,)h(Aout)g(\))334 4544 y(Sector)380 b(\()48 b(Xc,)f(Yc,)g(Amin,)f(Amax)h(\))0 4811 y Fj(where)28 b(\(Xc,Yc\))j(is)c(the)i(co)s(ordinate)g(of)f(the)h (shap)s(e's)f(cen)m(ter;)j(\(X#,Y#\))e(are)g(the)g(co)s(ordinates)f(of) h(the)g(shap)s(e's)0 4924 y(edges;)39 b(Rxxx)c(are)g(the)h(shap)s(es')f (v)-5 b(arious)34 b(Radii)g(or)h(semima)5 b(jor/minor)34 b(axes;)k(and)d(Axxx)g(are)h(the)g(angles)f(of)0 5036 y(rotation)d(\(or)f(b)s(ounding)e(angles)i(for)g(Sector\))h(in)e (degrees.)44 b(F)-8 b(or)32 b(rotated)h(shap)s(es,)e(the)g(rotation)h (angle)f(can)h(b)s(e)0 5149 y(left)f(o\013,)i(indicating)c(no)i (rotation.)45 b(Common)31 b(alternate)h(names)f(for)h(the)f(regions)g (can)h(also)g(b)s(e)e(used:)43 b(rotb)s(o)m(x)0 5262 y(=)29 b(b)s(o)m(x;)g(rotrectangle)h(=)f(rectangle;)h(\(rot\)rhom)m (bus)f(=)f(\(rot\)diamond;)i(and)e(pie)g(=)g(sector.)42 b(When)28 b(a)i(shap)s(e's)0 5375 y(name)e(is)f(preceded)g(b)m(y)h(a)g (min)m(us)f(sign,)g('-',)j(the)e(de\014ned)e(region)i(is)f(instead)g (the)h(area)h(*outside*)f(its)f(b)s(oundary)0 5488 y(\(ie,)35 b(the)f(region)g(is)f(in)m(v)m(erted\).)52 b(All)32 b(the)i(shap)s(es)f (within)f(a)i(single)f(region)g(\014le)h(are)g(OR'd)f(together)j(to)e (create)0 5601 y(the)29 b(region,)h(and)e(the)i(order)f(is)f (signi\014can)m(t.)39 b(The)29 b(o)m(v)m(erall)g(w)m(a)m(y)i(of)e(lo)s (oking)f(at)i(region)f(\014les)f(is)g(that)i(if)e(the)i(\014rst)0 5714 y(region)e(is)g(an)h(excluded)f(region)g(then)g(a)i(dumm)m(y)d (included)f(region)j(of)g(the)g(whole)f(detector)i(is)e(inserted)f(in)h (the)p eop %%Page: 126 134 126 133 bop 0 299 a Fj(126)1528 b Fh(CHAPTER)29 b(10.)113 b(EXTENDED)30 b(FILE)h(NAME)f(SYNT)-8 b(AX)0 555 y Fj(fron)m(t.)40 b(Then)25 b(eac)m(h)j(region)e(sp)s(eci\014cation)g(as)h(it)f(is)g(pro) s(cessed)g(o)m(v)m(errides)g(an)m(y)h(selections)g(inside)d(of)j(that)g (region)0 668 y(sp)s(eci\014ed)35 b(b)m(y)h(previous)f(regions.)58 b(Another)37 b(w)m(a)m(y)g(of)g(thinking)d(ab)s(out)i(this)f(is)h(that) h(if)e(a)i(previous)e(excluded)0 781 y(region)30 b(is)f(completely)h (inside)f(of)h(a)h(subsequen)m(t)e(included)f(region)i(the)h(excluded)e (region)h(is)f(ignored.)0 941 y(The)44 b(p)s(ositional)f(co)s (ordinates)i(ma)m(y)g(b)s(e)g(giv)m(en)g(either)f(in)g(pixel)f(units,)k (decimal)d(degrees)i(or)f(hh:mm:ss.s,)0 1054 y(dd:mm:ss.s)25 b(units.)37 b(The)26 b(shap)s(e)f(sizes)h(ma)m(y)g(b)s(e)g(giv)m(en)g (in)e(pixels,)i(degrees,)h(arcmin)m(utes,)g(or)f(arcseconds.)40 b(Lo)s(ok)0 1167 y(at)31 b(examples)f(of)g(region)g(\014le)g(pro)s (duced)e(b)m(y)i(fv/PO)m(W)h(or)g(ds9)f(for)g(further)f(details)g(of)i (the)f(region)g(\014le)f(format.)0 1327 y(There)37 b(are)g(three)g (functions)f(that)h(are)h(primarily)c(for)i(use)h(with)f(SA)m(O)h (region)f(\014les)g(and)h(the)g(FSA)m(OI)g(task,)0 1440 y(but)e(they)h(can)h(b)s(e)e(used)g(directly)-8 b(.)57 b(They)36 b(return)f(a)h(b)s(o)s(olean)f(true)h(or)g(false)f(dep)s (ending)f(on)i(whether)f(a)i(t)m(w)m(o)0 1553 y(dimensional)28 b(p)s(oin)m(t)h(is)g(in)g(the)i(region)f(or)g(not:)191 1815 y Fe("point)46 b(in)h(a)h(circular)d(region")477 1927 y(circle\(xcntr,ycntr,radius)o(,Xco)o(lumn)o(,Yc)o(olum)o(n\))191 2153 y("point)h(in)h(an)g(elliptical)e(region")430 2266 y(ellipse\(xcntr,ycntr,xhl)o(f_w)o(dth,)o(yhlf)o(_wd)o(th,r)o(otat)o (ion)o(,Xco)o(lumn)o(,Yc)o(olum)o(n\))191 2492 y("point)h(in)h(a)h (rectangular)c(region")620 2605 y(box\(xcntr,ycntr,xfll_wdth,)o(yfll)o (_wd)o(th,r)o(otat)o(ion)o(,Xco)o(lumn)o(,Yc)o(olum)o(n\))191 2831 y(where)334 2944 y(\(xcntr,ycntr\))g(are)j(the)g(\(x,y\))f (position)g(of)h(the)g(center)f(of)h(the)g(region)334 3057 y(\(xhlf_wdth,yhlf_wdth\))42 b(are)47 b(the)g(\(x,y\))f(half)h (widths)f(of)h(the)g(region)334 3169 y(\(xfll_wdth,yfll_wdth\))42 b(are)47 b(the)g(\(x,y\))f(full)h(widths)f(of)h(the)g(region)334 3282 y(\(radius\))f(is)h(half)f(the)h(diameter)f(of)h(the)g(circle)334 3395 y(\(rotation\))e(is)i(the)g(angle\(degrees\))d(that)j(the)g (region)f(is)h(rotated)f(with)620 3508 y(respect)g(to)h (\(xcntr,ycntr\))334 3621 y(\(Xcoord,Ycoord\))d(are)j(the)g(\(x,y\))f (coordinates)f(to)i(test,)f(usually)g(column)620 3734 y(names)334 3847 y(NOTE:)g(each)h(parameter)e(can)i(itself)f(be)i(an)f (expression,)d(not)j(merely)f(a)620 3960 y(column)h(name)f(or)h (constant.)0 4253 y Fd(10.10.6)113 b(Example)36 b(Ro)m(w)h(Filters)191 4472 y Fe([)47 b(binary)f(&&)i(mag)f(<=)g(5.0])380 b(-)48 b(Extract)e(all)h(binary)f(stars)g(brighter)1766 4585 y(than)94 b(fifth)47 b(magnitude)e(\(note)h(that)1766 4698 y(the)h(initial)f(space)g(is)h(necessary)e(to)1766 4811 y(prevent)h(it)h(from)g(being)f(treated)g(as)h(a)1766 4924 y(binning)f(specification\))191 5149 y([#row)g(>=)h(125)g(&&)h (#row)e(<=)h(175])142 b(-)48 b(Extract)e(row)h(numbers)e(125)i(through) f(175)191 5375 y([IMAGE[4,5])f(.gt.)h(100])476 b(-)48 b(Extract)e(all)h(rows)f(that)h(have)g(the)1766 5488 y(\(4,5\))f(component)g(of)h(the)g(IMAGE)f(column)1766 5601 y(greater)g(than)g(100)p eop %%Page: 127 135 127 134 bop 0 299 a Fh(10.11.)113 b(BINNING)32 b(OR)e(HISTOGRAMMING)g (SPECIFICA)-8 b(TION)1223 b Fj(127)191 555 y Fe([abs\(sin\(theta)44 b(*)j(#deg\)\))f(<)i(0.5])e(-)i(Extract)e(all)h(rows)f(having)g(the) 1766 668 y(absolute)f(value)i(of)g(the)g(sine)g(of)g(theta)1766 781 y(less)94 b(than)47 b(a)g(half)g(where)f(the)h(angles)1766 894 y(are)g(tabulated)e(in)i(degrees)191 1120 y([SUM\()f(SPEC)h(>)g (3*BACKGRND)e(\)>=1])94 b(-)48 b(Extract)e(all)h(rows)f(containing)f(a) 1766 1233 y(spectrum,)g(held)i(in)g(vector)f(column)1766 1346 y(SPEC,)g(with)h(at)g(least)f(one)h(value)g(3)1766 1458 y(times)f(greater)g(than)h(the)g(background)1766 1571 y(level)f(held)h(in)g(a)h(keyword,)d(BACKGRND)191 1797 y([VCOL=={1,4,2}])759 b(-)48 b(Extract)e(all)h(rows)f(whose)h (vector)f(column)1766 1910 y(VCOL)h(contains)e(the)i(3-elements)e(1,)i (4,)g(and)1766 2023 y(2.)191 2249 y([@rowFilter.txt])711 b(-)48 b(Extract)e(rows)g(using)h(the)g(expression)1766 2362 y(contained)e(within)h(the)h(text)g(file)1766 2475 y(rowFilter.txt)191 2700 y([gtifilter\(\)])855 b(-)48 b(Search)e(the)h(current)f(file)g(for)h(a)h(GTI)239 2813 y(extension,)92 b(filter)i(the)47 b(TIME)239 2926 y(column)f(in)h(the)g (current)f(table,)g(using)239 3039 y(START/STOP)f(times)h(taken)g(from) 239 3152 y(columns)f(in)j(the)f(GTI)94 b(extension)191 3378 y([regfilter\("pow.reg"\)])423 b(-)48 b(Extract)e(rows)g(which)h (have)f(a)i(coordinate)1766 3491 y(\(as)f(given)f(in)h(the)g(X)h(and)f (Y)g(columns\))1766 3604 y(within)f(the)h(spatial)f(region)g(specified) 1766 3717 y(in)h(the)g(pow.reg)f(region)g(file.)191 3942 y([regfilter\("pow.reg",)c(Xs,)47 b(Ys\)])f(-)i(Same)f(as)g(above,)f (except)g(that)h(the)1766 4055 y(Xs)g(and)g(Ys)g(columns)f(will)h(be)g (used)f(to)1766 4168 y(determine)f(the)i(coordinate)e(of)i(each)1766 4281 y(row)g(in)g(the)g(table.)0 4664 y Ff(10.11)181 b(Binning)44 b(or)h(Histogramming)i(Sp)t(eci\014cation)0 4924 y Fj(The)22 b(optional)g(binning)e(sp)s(eci\014er)h(is)h(enclosed) h(in)f(square)g(brac)m(k)m(ets)j(and)d(can)h(b)s(e)f(distinguished)d (from)k(a)g(general)0 5036 y(ro)m(w)32 b(\014lter)g(sp)s(eci\014cation) f(b)m(y)h(the)h(fact)g(that)g(it)f(b)s(egins)f(with)g(the)h(k)m(eyw)m (ord)h('bin')e(not)i(immediately)d(follo)m(w)m(ed)0 5149 y(b)m(y)41 b(an)f(equals)h(sign.)71 b(When)41 b(binning)c(is)j(sp)s (eci\014ed,)i(a)f(temp)s(orary)g(N-dimensional)d(FITS)i(primary)f(arra) m(y)0 5262 y(is)j(created)i(b)m(y)f(computing)g(the)g(histogram)g(of)g (the)g(v)-5 b(alues)43 b(in)e(the)j(sp)s(eci\014ed)d(columns)h(of)h(a)h (FITS)e(table)0 5375 y(extension.)e(After)30 b(the)f(histogram)g(is)g (computed)g(the)h(input)d(FITS)i(\014le)g(con)m(taining)g(the)g(table)h (is)e(then)h(closed)0 5488 y(and)34 b(the)h(temp)s(orary)f(FITS)g (primary)f(arra)m(y)i(is)f(op)s(ened)g(and)g(passed)g(to)h(the)g (application)e(program.)54 b(Th)m(us,)0 5601 y(the)39 b(application)e(program)i(nev)m(er)g(sees)g(the)g(original)e(FITS)h (table)h(and)f(only)g(sees)i(the)f(image)g(in)e(the)i(new)0 5714 y(temp)s(orary)32 b(\014le)g(\(whic)m(h)g(has)g(no)h(additional)d (extensions\).)48 b(Ob)m(viously)-8 b(,)32 b(the)h(application)e (program)h(m)m(ust)h(b)s(e)p eop %%Page: 128 136 128 135 bop 0 299 a Fj(128)1528 b Fh(CHAPTER)29 b(10.)113 b(EXTENDED)30 b(FILE)h(NAME)f(SYNT)-8 b(AX)0 555 y Fj(exp)s(ecting)30 b(to)h(op)s(en)f(a)h(FITS)e(image)i(and)f(not)g(a)h(FITS)f(table)g(in)f (this)g(case.)0 715 y(The)h(data)h(t)m(yp)s(e)f(of)h(the)f(FITS)g (histogram)f(image)i(ma)m(y)g(b)s(e)f(sp)s(eci\014ed)e(b)m(y)i(app)s (ending)e('b')i(\(for)h(8-bit)f(b)m(yte\),)h('i')0 828 y(\(for)g(16-bit)f(in)m(tegers\),)h('j')g(\(for)g(32-bit)f(in)m (teger\),)i('r')e(\(for)h(32-bit)f(\015oating)h(p)s(oin)m(ts\),)e(or)i ('d')f(\(for)h(64-bit)f(double)0 941 y(precision)i(\015oating)j(p)s (oin)m(t\))e(to)i(the)g('bin')e(k)m(eyw)m(ord)i(\(e.g.)54 b('[binr)32 b(X]')j(creates)h(a)f(real)f(\015oating)g(p)s(oin)m(t)f (image\).)0 1054 y(If)h(the)i(data)f(t)m(yp)s(e)g(is)f(not)i (explicitly)c(sp)s(eci\014ed)h(then)i(a)g(32-bit)h(in)m(teger)f(image)g (will)d(b)s(e)j(created)h(b)m(y)e(default,)0 1167 y(unless)23 b(the)j(w)m(eigh)m(ting)e(option)h(is)f(also)h(sp)s(eci\014ed)e(in)h (whic)m(h)g(case)i(the)f(image)h(will)c(ha)m(v)m(e)k(a)g(32-bit)f (\015oating)g(p)s(oin)m(t)0 1280 y(data)31 b(t)m(yp)s(e)g(b)m(y)f (default.)0 1440 y(The)24 b(histogram)f(image)i(ma)m(y)g(ha)m(v)m(e)g (from)f(1)g(to)h(4)g(dimensions)c(\(axes\),)27 b(dep)s(ending)22 b(on)i(the)g(n)m(um)m(b)s(er)f(of)h(columns)0 1553 y(that)31 b(are)g(sp)s(eci\014ed.)39 b(The)30 b(general)g(form)g(of)g(the)h (binning)c(sp)s(eci\014cation)i(is:)48 1767 y Fe([bin{bijrd})92 b(Xcol=min:max:binsize,)42 b(Ycol=)47 b(...,)f(Zcol=...,)f(Tcol=...;)h (weight])0 1982 y Fj(in)38 b(whic)m(h)g(up)g(to)i(4)g(columns,)g(eac)m (h)g(corresp)s(onding)d(to)j(an)g(axis)e(of)i(the)f(image,)j(are)e (listed.)65 b(The)39 b(column)0 2095 y(names)27 b(are)h(case)h (insensitiv)m(e,)d(and)h(the)h(column)e(n)m(um)m(b)s(er)g(ma)m(y)i(b)s (e)f(giv)m(en)g(instead)g(of)h(the)g(name,)g(preceded)f(b)m(y)0 2208 y(a)32 b(p)s(ound)e(sign)h(\(e.g.,)j([bin)c(#4=1:512]\).)47 b(If)31 b(the)h(column)f(name)h(is)e(not)i(sp)s(eci\014ed,)f(then)g (CFITSIO)g(will)e(\014rst)0 2321 y(try)37 b(to)h(use)f(the)g ('preferred)f(column')h(as)g(sp)s(eci\014ed)f(b)m(y)h(the)g(CPREF)g(k)m (eyw)m(ord)h(if)e(it)g(exists)h(\(e.g.,)k('CPREF)0 2433 y(=)i('DETX,DETY'\),)h(otherwise)f(column)f(names)h('X',)h('Y',)g('Z',) f(and)f('T')i(will)c(b)s(e)i(assumed)h(for)g(eac)m(h)h(of)0 2546 y(the)37 b(4)h(axes,)i(resp)s(ectiv)m(ely)-8 b(.)60 b(In)37 b(cases)h(where)e(the)i(column)e(name)h(could)f(b)s(e)g (confused)h(with)f(an)h(arithmetic)0 2659 y(expression,)29 b(enclose)i(the)g(column)e(name)h(in)f(paren)m(theses)i(to)g(force)g (the)f(name)h(to)g(b)s(e)f(in)m(terpreted)f(literally)-8 b(.)0 2819 y(Eac)m(h)33 b(column)e(name)h(ma)m(y)h(b)s(e)f(follo)m(w)m (ed)f(b)m(y)i(an)f(equals)f(sign)h(and)f(then)h(the)g(lo)m(w)m(er)h (and)f(upp)s(er)e(range)i(of)h(the)0 2932 y(histogram,)e(and)f(the)h (size)g(of)g(the)g(histogram)g(bins,)e(separated)i(b)m(y)g(colons.)42 b(Spaces)31 b(are)g(allo)m(w)m(ed)g(b)s(efore)g(and)0 3045 y(after)e(the)g(equals)f(sign)f(but)h(not)h(within)d(the)j ('min:max:binsize')d(string.)39 b(The)29 b(min,)e(max)i(and)f(binsize)f (v)-5 b(alues)0 3158 y(ma)m(y)32 b(b)s(e)e(in)m(teger)h(or)g (\015oating)g(p)s(oin)m(t)f(n)m(um)m(b)s(ers,)g(or)h(they)g(ma)m(y)g(b) s(e)g(the)g(names)g(of)g(k)m(eyw)m(ords)g(in)f(the)h(header)g(of)0 3271 y(the)g(table.)40 b(If)30 b(the)h(latter,)g(then)f(the)g(v)-5 b(alue)30 b(of)h(that)g(k)m(eyw)m(ord)f(is)g(substituted)f(in)m(to)h (the)h(expression.)0 3431 y(Default)36 b(v)-5 b(alues)35 b(for)h(the)g(min,)g(max)g(and)g(binsize)e(quan)m(tities)h(will)e(b)s (e)i(used)h(if)e(not)j(explicitly)c(giv)m(en)j(in)f(the)0 3544 y(binning)27 b(expression)i(as)i(sho)m(wn)f(in)f(these)i (examples:)191 3759 y Fe([bin)47 b(x)g(=)g(:512:2])94 b(-)47 b(use)g(default)f(minimum)g(value)191 3871 y([bin)h(x)g(=)g (1::2])190 b(-)47 b(use)g(default)f(maximum)g(value)191 3984 y([bin)h(x)g(=)g(1:512])142 b(-)47 b(use)g(default)f(bin)h(size) 191 4097 y([bin)g(x)g(=)g(1:])286 b(-)47 b(use)g(default)f(maximum)g (value)g(and)h(bin)g(size)191 4210 y([bin)g(x)g(=)g(:512])190 b(-)47 b(use)g(default)f(minimum)g(value)g(and)h(bin)g(size)191 4323 y([bin)g(x)g(=)g(2])334 b(-)47 b(use)g(default)f(minimum)g(and)h (maximum)f(values)191 4436 y([bin)h(x])524 b(-)47 b(use)g(default)f (minimum,)g(maximum)g(and)g(bin)h(size)191 4549 y([bin)g(4])524 b(-)47 b(default)f(2-D)h(image,)f(bin)h(size)g(=)g(4)h(in)f(both)g (axes)191 4662 y([bin])619 b(-)47 b(default)f(2-D)h(image)0 4876 y Fj(CFITSIO)31 b(will)f(use)i(the)h(v)-5 b(alue)32 b(of)h(the)g(TLMINn,)f(TLMAXn,)h(and)f(TDBINn)h(k)m(eyw)m(ords,)h(if)d (they)i(exist,)g(for)0 4989 y(the)k(default)e(min,)i(max,)h(and)e (binsize,)g(resp)s(ectiv)m(ely)-8 b(.)59 b(If)36 b(they)h(do)f(not)h (exist)f(then)g(CFITSIO)f(will)f(use)i(the)0 5102 y(actual)c(minim)m (um)d(and)j(maxim)m(um)f(v)-5 b(alues)31 b(in)g(the)h(column)e(for)i (the)g(histogram)g(min)e(and)i(max)g(v)-5 b(alues.)44 b(The)0 5215 y(default)33 b(binsize)e(will)g(b)s(e)i(set)h(to)h(1,)g (or)e(\(max)h(-)g(min\))e(/)i(10.,)i(whic)m(hev)m(er)d(is)g(smaller,)g (so)g(that)i(the)e(histogram)0 5328 y(will)28 b(ha)m(v)m(e)j(at)g (least)g(10)g(bins)e(along)h(eac)m(h)i(axis.)0 5488 y(A)41 b(shortcut)g(notation)g(is)f(allo)m(w)m(ed)h(if)f(all)g(the)h (columns/axes)g(ha)m(v)m(e)h(the)f(same)g(binning)d(sp)s (eci\014cation.)72 b(In)0 5601 y(this)32 b(case)h(all)f(the)h(column)e (names)i(ma)m(y)g(b)s(e)f(listed)f(within)f(paren)m(theses,)k(follo)m (w)m(ed)f(b)m(y)f(the)h(\(single\))f(binning)0 5714 y(sp)s (eci\014cation,)d(as)i(in:)p eop %%Page: 129 137 129 136 bop 0 299 a Fh(10.11.)113 b(BINNING)32 b(OR)e(HISTOGRAMMING)g (SPECIFICA)-8 b(TION)1223 b Fj(129)191 555 y Fe([bin)47 b(\(X,Y\)=1:512:2])191 668 y([bin)g(\(X,Y\))f(=)h(5])0 888 y Fj(The)31 b(optional)g(w)m(eigh)m(ting)h(factor)g(is)f(the)h (last)f(item)h(in)e(the)i(binning)d(sp)s(eci\014er)h(and,)i(if)e (presen)m(t,)j(is)d(separated)0 1001 y(from)38 b(the)g(list)f(of)h (columns)f(b)m(y)h(a)h(semi-colon.)63 b(As)39 b(the)f(histogram)g(is)f (accum)m(ulated,)k(this)c(w)m(eigh)m(t)i(is)e(used)0 1114 y(to)e(incremen)m(ted)e(the)h(v)-5 b(alue)34 b(of)g(the)g (appropriated)e(bin)h(in)f(the)i(histogram.)51 b(If)34 b(the)g(w)m(eigh)m(ting)g(factor)h(is)e(not)0 1227 y(sp)s(eci\014ed,)23 b(then)g(the)g(default)f(w)m(eigh)m(t)i(=)e(1)i(is)e(assumed.)37 b(The)23 b(w)m(eigh)m(ting)g(factor)h(ma)m(y)f(b)s(e)g(a)g(constan)m(t) i(in)m(teger)e(or)0 1340 y(\015oating)29 b(p)s(oin)m(t)f(n)m(um)m(b)s (er,)g(or)h(the)g(name)g(of)g(a)g(k)m(eyw)m(ord)h(con)m(taining)e(the)i (w)m(eigh)m(ting)e(v)-5 b(alue.)40 b(Or)28 b(the)h(w)m(eigh)m(ting)0 1453 y(factor)g(ma)m(y)g(b)s(e)e(the)h(name)g(of)h(a)f(table)g(column)f (in)g(whic)m(h)f(case)k(the)e(v)-5 b(alue)27 b(in)g(that)i(column,)e (on)h(a)h(ro)m(w)f(b)m(y)g(ro)m(w)0 1566 y(basis,)h(will)f(b)s(e)i (used.)0 1726 y(In)35 b(some)h(cases,)i(the)d(column)g(or)g(k)m(eyw)m (ord)h(ma)m(y)g(giv)m(e)g(the)g(recipro)s(cal)e(of)i(the)g(actual)g(w)m (eigh)m(t)g(v)-5 b(alue)35 b(that)h(is)0 1839 y(needed.)49 b(In)32 b(this)g(case,)j(precede)e(the)h(w)m(eigh)m(t)f(k)m(eyw)m(ord)h (or)f(column)f(name)h(b)m(y)g(a)g(slash)f('/')i(to)g(tell)e(CFITSIO)0 1952 y(to)f(use)f(the)h(recipro)s(cal)e(of)h(the)h(v)-5 b(alue)30 b(when)f(constructing)h(the)h(histogram.)0 2112 y(F)-8 b(or)25 b(complex)f(or)g(commonly)f(used)h(histograms,)h (one)f(can)h(also)f(place)g(its)f(description)f(in)m(to)i(a)h(text)g (\014le)e(and)h(im-)0 2225 y(p)s(ort)e(it)f(in)m(to)h(the)h(binning)c (sp)s(eci\014cation)i(using)f(the)j(syn)m(tax)f([bin)f (@\014lename.txt].)38 b(The)22 b(\014le's)f(con)m(ten)m(ts)j(can)e(ex-) 0 2338 y(tend)h(o)m(v)m(er)i(m)m(ultiple)c(lines,)i(although)g(it)g(m)m (ust)g(still)e(conform)i(to)h(the)g(no-spaces)g(rule)e(for)h(the)h (min:max:binsize)0 2451 y(syn)m(tax)35 b(and)f(eac)m(h)h(axis)f(sp)s (eci\014cation)g(m)m(ust)g(still)e(b)s(e)i(comma-separated.)55 b(An)m(y)34 b(lines)f(in)g(the)i(external)f(text)0 2564 y(\014le)26 b(that)h(b)s(egin)f(with)f(2)j(slash)d(c)m(haracters)k (\('//'\))g(will)24 b(b)s(e)i(ignored)g(and)g(ma)m(y)i(b)s(e)e(used)g (to)i(add)e(commen)m(ts)i(in)m(to)0 2676 y(the)j(\014le.)0 2837 y(Examples:)191 3057 y Fe([bini)46 b(detx,)h(dety])762 b(-)47 b(2-D,)g(16-bit)f(integer)g(histogram)1861 3170 y(of)i(DETX)e(and)h(DETY)g(columns,)e(using)1861 3283 y(default)h(values)g(for)h(the)g(histogram)1861 3396 y(range)g(and)g(binsize)191 3621 y([bin)g(\(detx,)f(dety\)=16;)f (/exposure])g(-)i(2-D,)g(32-bit)f(real)h(histogram)e(of)i(DETX)1861 3734 y(and)g(DETY)g(columns)f(with)g(a)i(bin)f(size)f(=)i(16)1861 3847 y(in)g(both)e(axes.)h(The)f(histogram)g(values)1861 3960 y(are)h(divided)f(by)h(the)g(EXPOSURE)f(keyword)1861 4073 y(value.)191 4299 y([bin)h(time=TSTART:TSTOP:0.1])280 b(-)47 b(1-D)g(lightcurve,)e(range)h(determined)f(by)1861 4412 y(the)i(TSTART)f(and)h(TSTOP)g(keywords,)1861 4525 y(with)g(0.1)g(unit)g(size)f(bins.)191 4751 y([bin)h(pha,)f (time=8000.:8100.:0.1])90 b(-)47 b(2-D)g(image)g(using)f(default)g (binning)1861 4863 y(of)i(the)e(PHA)h(column)f(for)h(the)g(X)h(axis,) 1861 4976 y(and)f(1000)g(bins)g(in)g(the)g(range)1861 5089 y(8000.)g(to)g(8100.)f(for)h(the)g(Y)h(axis.)191 5315 y([bin)f(@binFilter.txt])616 b(-)47 b(Use)g(the)g(contents)f(of)h (the)g(text)f(file)1861 5428 y(binFilter.txt)f(for)h(the)h(binning)1861 5541 y(specifications.)p eop %%Page: 130 138 130 137 bop 0 299 a Fj(130)1528 b Fh(CHAPTER)29 b(10.)113 b(EXTENDED)30 b(FILE)h(NAME)f(SYNT)-8 b(AX)p eop %%Page: 131 139 131 138 bop 0 1225 a Fg(Chapter)65 b(11)0 1687 y Fm(T)-19 b(emplate)76 b(Files)0 2180 y Fj(When)38 b(a)h(new)f(FITS)g(\014le)g (is)g(created)h(with)f(a)g(call)g(to)i(\014ts)p 2101 2180 28 4 v 32 w(create)p 2369 2180 V 35 w(\014le,)f(the)g(name)g(of)g (a)g(template)g(\014le)e(ma)m(y)0 2293 y(b)s(e)i(supplied)e(in)i(paren) m(theses)h(immediately)e(follo)m(wing)g(the)j(name)f(of)g(the)g(new)f (\014le)g(to)i(b)s(e)e(created.)71 b(This)0 2406 y(template)26 b(is)e(used)h(to)h(de\014ne)f(the)h(structure)f(of)h(one)f(or)h(more)g (HDUs)g(in)e(the)i(new)f(\014le.)38 b(The)25 b(template)h(\014le)e(ma)m (y)0 2518 y(b)s(e)32 b(another)h(FITS)f(\014le,)h(in)f(whic)m(h)f(case) j(the)f(newly)f(created)i(\014le)e(will)e(ha)m(v)m(e)k(exactly)g(the)f (same)g(k)m(eyw)m(ords)g(in)0 2631 y(eac)m(h)25 b(HDU)g(as)g(in)e(the)h (template)h(FITS)e(\014le,)i(but)e(all)h(the)g(data)h(units)d(will)g(b) s(e)i(\014lled)e(with)g(zeros.)40 b(The)24 b(template)0 2744 y(\014le)h(ma)m(y)i(also)f(b)s(e)f(an)h(ASCI)s(I)e(text)j(\014le,) f(where)g(eac)m(h)h(line)d(\(in)h(general\))i(describ)s(es)d(one)i (FITS)f(k)m(eyw)m(ord)i(record.)0 2857 y(The)j(format)h(of)f(the)h (ASCI)s(I)e(template)h(\014le)g(is)f(describ)s(ed)f(in)i(the)g(follo)m (wing)f(sections.)0 3188 y Ff(11.1)136 b(Detailed)46 b(T)-11 b(emplate)46 b(Line)f(F)-11 b(ormat)0 3438 y Fj(The)30 b(format)h(of)f(eac)m(h)i(ASCI)s(I)c(template)j(line)e (closely)h(follo)m(ws)f(the)i(format)g(of)f(a)h(FITS)f(k)m(eyw)m(ord)g (record:)95 3682 y Fe(KEYWORD)46 b(=)i(KEYVALUE)d(/)j(COMMENT)0 3926 y Fj(except)22 b(that)g(free)g(format)f(ma)m(y)h(b)s(e)f(used)f (\(e.g.,)25 b(the)d(equals)e(sign)h(ma)m(y)g(app)s(ear)g(at)h(an)m(y)g (p)s(osition)d(in)h(the)i(line\))e(and)0 4039 y(T)-8 b(AB)34 b(c)m(haracters)g(are)g(allo)m(w)m(ed)f(and)g(are)g(treated)h (the)g(same)f(as)h(space)f(c)m(haracters.)51 b(The)33 b(KEYV)-10 b(ALUE)33 b(and)0 4152 y(COMMENT)d(\014elds)f(are)i (optional.)41 b(The)30 b(equals)g(sign)f(c)m(haracter)k(is)c(also)i (optional,)f(but)g(it)g(is)f(recommended)0 4264 y(that)42 b(it)e(b)s(e)h(included)d(for)j(clarit)m(y)-8 b(.)73 b(An)m(y)41 b(template)h(line)d(that)j(b)s(egins)e(with)f(the)j(p)s (ound)d('#')i(c)m(haracter)i(is)0 4377 y(ignored)29 b(b)m(y)i(the)f (template)h(parser)f(and)g(ma)m(y)h(b)s(e)e(use)h(to)h(insert)f(commen) m(ts)h(in)m(to)f(the)h(template)g(\014le)e(itself.)0 4538 y(The)d(KEYW)m(ORD)g(name)g(\014eld)f(is)g(limited)f(to)j(8)f(c)m (haracters)h(in)e(length)h(and)f(only)g(the)h(letters)h(A-Z,)f(digits)f (0-9,)0 4650 y(and)j(the)g(h)m(yphen)f(and)h(underscore)g(c)m (haracters)h(ma)m(y)g(b)s(e)f(used,)g(without)g(an)m(y)g(em)m(b)s (edded)g(spaces.)40 b(Lo)m(w)m(ercase)0 4763 y(letters)21 b(in)f(the)i(template)f(k)m(eyw)m(ord)h(name)f(will)d(b)s(e)j(con)m(v)m (erted)i(to)f(upp)s(ercase.)36 b(Leading)21 b(spaces)g(in)f(the)i (template)0 4876 y(line)i(preceding)h(the)g(k)m(eyw)m(ord)h(name)g(are) g(generally)f(ignored,)h(except)g(if)f(the)h(\014rst)f(8)h(c)m (haracters)h(of)f(a)g(template)0 4989 y(line)d(are)j(all)e(blank,)h (then)g(the)g(en)m(tire)g(line)f(is)g(treated)i(as)f(a)h(FITS)e(commen) m(t)i(k)m(eyw)m(ord)g(\(with)e(a)i(blank)d(k)m(eyw)m(ord)0 5102 y(name\))31 b(and)f(is)f(copied)h(v)m(erbatim)g(in)m(to)g(the)h (FITS)e(header.)0 5262 y(The)37 b(KEYV)-10 b(ALUE)37 b(\014eld)f(ma)m(y)i(ha)m(v)m(e)g(an)m(y)g(allo)m(w)m(ed)f(FITS)g(data) h(t)m(yp)s(e:)54 b(c)m(haracter)39 b(string,)g(logical,)f(in)m(teger,)0 5375 y(real,)33 b(complex)f(in)m(teger,)i(or)e(complex)h(real.)46 b(The)32 b(c)m(haracter)j(string)c(v)-5 b(alues)32 b(need)g(not)h(b)s (e)f(enclosed)g(in)f(single)0 5488 y(quote)e(c)m(haracters)h(unless)d (they)h(are)h(necessary)g(to)g(distinguish)24 b(the)29 b(string)e(from)h(a)h(di\013eren)m(t)f(data)h(t)m(yp)s(e)f(\(e.g.)0 5601 y(2.0)h(is)d(a)i(real)g(but)f('2.0')i(is)e(a)h(string\).)39 b(The)27 b(k)m(eyw)m(ord)h(has)f(an)h(unde\014ned)d(\(n)m(ull\))h(v)-5 b(alue)28 b(if)e(the)i(template)g(record)0 5714 y(only)h(con)m(tains)i (blanks)e(follo)m(wing)g(the)h("=")h(or)g(b)s(et)m(w)m(een)g(the)f("=") h(and)f(the)g("/")i(commen)m(t)g(\014eld)c(delimiter.)1882 5942 y(131)p eop %%Page: 132 140 132 139 bop 0 299 a Fj(132)2250 b Fh(CHAPTER)29 b(11.)72 b(TEMPLA)-8 b(TE)30 b(FILES)0 555 y Fj(String)25 b(k)m(eyw)m(ord)i(v)-5 b(alues)26 b(longer)g(than)g(68)h(c)m(haracters)h(\(the)f(maxim)m(um)e (length)h(that)h(will)d(\014t)i(in)f(a)i(single)e(FITS)0 668 y(k)m(eyw)m(ord)41 b(record\))g(are)g(p)s(ermitted)e(using)g(the)i (CFITSIO)e(long)h(string)g(con)m(v)m(en)m(tion.)73 b(They)40 b(can)h(either)f(b)s(e)0 781 y(sp)s(eci\014ed)27 b(as)j(a)f(single)f (long)g(line)g(in)f(the)j(template,)g(or)f(b)m(y)f(using)g(m)m(ultiple) f(lines)g(where)h(the)i(con)m(tin)m(uing)e(lines)0 894 y(con)m(tain)j(the)f('CONTINUE')g(k)m(eyw)m(ord,)h(as)g(in)e(this)g (example:)95 1139 y Fe(LONGKEY)46 b(=)i('This)e(is)h(a)h(long)e(string) g(value)h(that)f(is)i(contin&')95 1252 y(CONTINUE)94 b('ued)46 b(over)h(2)g(records')f(/)h(comment)f(field)h(goes)f(here)0 1497 y Fj(The)29 b(format)h(of)g(template)g(lines)d(with)i(CONTINUE)f (k)m(eyw)m(ord)i(is)f(v)m(ery)h(strict:)40 b(3)30 b(spaces)g(m)m(ust)f (follo)m(w)g(CON-)0 1610 y(TINUE)h(and)g(the)g(rest)h(of)f(the)h(line)e (is)g(copied)h(v)m(erbatim)g(to)h(the)g(FITS)e(\014le.)0 1771 y(The)i(start)h(of)g(the)f(optional)g(COMMENT)g(\014eld)f(m)m(ust) i(b)s(e)e(preceded)i(b)m(y)f("/",)i(whic)m(h)d(is)h(used)g(to)h (separate)g(it)0 1883 y(from)e(the)g(k)m(eyw)m(ord)h(v)-5 b(alue)29 b(\014eld.)40 b(Exceptions)29 b(are)i(if)e(the)i(KEYW)m(ORD)g (name)f(\014eld)f(con)m(tains)h(COMMENT,)0 1996 y(HISTOR)-8 b(Y,)30 b(CONTINUE,)g(or)g(if)f(the)i(\014rst)f(8)g(c)m(haracters)i(of) f(the)f(template)h(line)e(are)i(blanks.)0 2157 y(More)c(than)f(one)h (Header-Data)i(Unit)d(\(HDU\))h(ma)m(y)g(b)s(e)f(de\014ned)f(in)g(the)i (template)g(\014le.)38 b(The)26 b(start)h(of)g(an)f(HDU)0 2269 y(de\014nition)i(is)h(denoted)i(with)e(a)i(SIMPLE)e(or)i(XTENSION) e(template)i(line:)0 2430 y(1\))j(SIMPLE)f(b)s(egins)f(a)i(Primary)f (HDU)h(de\014nition.)48 b(SIMPLE)33 b(ma)m(y)h(only)f(app)s(ear)g(as)h (the)g(\014rst)f(k)m(eyw)m(ord)h(in)0 2543 y(the)e(template)h(\014le.) 44 b(If)32 b(the)g(template)h(\014le)e(b)s(egins)f(with)h(XTENSION)g (instead)g(of)h(SIMPLE,)g(then)f(a)i(default)0 2655 y(empt)m(y)d (Primary)d(HDU)j(is)f(created,)i(and)d(the)i(template)g(is)e(then)h (assumed)f(to)i(de\014ne)f(the)h(k)m(eyw)m(ords)f(starting)0 2768 y(with)g(the)i(\014rst)e(extension)h(follo)m(wing)f(the)i(Primary) e(HDU.)0 2928 y(2\))35 b(XTENSION)e(marks)g(the)i(b)s(eginning)c(of)j (a)h(new)e(extension)h(HDU)g(de\014nition.)50 b(The)33 b(previous)g(HDU)i(will)0 3041 y(b)s(e)30 b(closed)g(at)h(this)e(p)s (oin)m(t)h(and)f(pro)s(cessing)h(of)g(the)h(next)f(extension)g(b)s (egins.)0 3373 y Ff(11.2)136 b(Auto-indexing)45 b(of)g(Keyw)l(ords)0 3623 y Fj(If)31 b(a)h(template)f(k)m(eyw)m(ord)h(name)f(ends)g(with)f (a)h("#")h(c)m(haracter,)i(it)d(is)f(said)g(to)i(b)s(e)f ('auto-indexed'.)43 b(Eac)m(h)32 b("#")0 3736 y(c)m(haracter)i(will)c (b)s(e)i(replaced)h(b)m(y)f(the)h(curren)m(t)g(in)m(teger)g(index)e(v) -5 b(alue,)33 b(whic)m(h)f(gets)h(reset)h(=)e(1)h(at)h(the)e(start)i (of)0 3849 y(eac)m(h)h(new)f(HDU)g(in)f(the)h(\014le)f(\(or)h(7)h(in)d (the)i(sp)s(ecial)f(case)i(of)f(a)g(GR)m(OUP)h(de\014nition\).)49 b(The)33 b(FIRST)g(indexed)0 3962 y(k)m(eyw)m(ord)c(in)e(eac)m(h)i (template)g(HDU)g(de\014nition)d(is)h(used)g(as)i(the)f('incremen)m (tor';)i(eac)m(h)f(subsequen)m(t)f(o)s(ccurrence)0 4075 y(of)k(this)e(SAME)h(k)m(eyw)m(ord)h(will)d(cause)j(the)g(index)e(v)-5 b(alue)31 b(to)h(b)s(e)f(incremen)m(ted.)43 b(This)30 b(b)s(eha)m(vior)g(can)i(b)s(e)f(rather)0 4188 y(subtle,)c(as)h (illustrated)e(in)g(the)i(follo)m(wing)e(examples)h(in)f(whic)m(h)h (the)h(TTYPE)e(k)m(eyw)m(ord)i(is)f(the)h(incremen)m(tor)f(in)0 4300 y(b)s(oth)j(cases:)95 4546 y Fe(TTYPE#)47 b(=)g(TIME)95 4659 y(TFORM#)g(=)g(1D)95 4772 y(TTYPE#)g(=)g(RATE)95 4884 y(TFORM#)g(=)g(1E)0 5130 y Fj(will)23 b(create)28 b(TTYPE1,)e(TF)m(ORM1,)i(TTYPE2,)f(and)e(TF)m(ORM2)i(k)m(eyw)m(ords.)40 b(But)26 b(if)f(the)h(template)g(lo)s(oks)f(lik)m(e,)95 5375 y Fe(TTYPE#)47 b(=)g(TIME)95 5488 y(TTYPE#)g(=)g(RATE)95 5601 y(TFORM#)g(=)g(1D)95 5714 y(TFORM#)g(=)g(1E)p eop %%Page: 133 141 133 140 bop 0 299 a Fh(11.3.)73 b(TEMPLA)-8 b(TE)30 b(P)-8 b(ARSER)30 b(DIRECTIVES)1982 b Fj(133)0 555 y(this)30 b(results)f(in)h(a)h(FITS)f(\014les)g(with)f(TTYPE1,)i(TTYPE2,)g(TF)m (ORM2,)h(and)e(TF)m(ORM2,)i(whic)m(h)e(is)g(probably)0 668 y(not)h(what)f(w)m(as)h(in)m(tended!)0 1000 y Ff(11.3)136 b(T)-11 b(emplate)45 b(P)l(arser)h(Directiv)l(es)0 1251 y Fj(In)29 b(addition)g(to)h(the)g(template)h(lines)d(whic)m(h)h (de\014ne)g(individual)d(k)m(eyw)m(ords,)k(the)g(template)h(parser)e (recognizes)0 1363 y(3)h(sp)s(ecial)f(directiv)m(es)g(whic)m(h)g(are)h (eac)m(h)h(preceded)f(b)m(y)f(the)h(bac)m(kslash)g(c)m(haracter:)90 b Fe(\\include,)45 b(\\group)p Fj(,)29 b(and)48 1476 y Fe(\\end)p Fj(.)0 1637 y(The)37 b('include')f(directiv)m(e)i(m)m(ust) f(b)s(e)h(follo)m(w)m(ed)f(b)m(y)h(a)g(\014lename.)62 b(It)38 b(forces)g(the)g(parser)f(to)i(temp)s(orarily)d(stop)0 1749 y(reading)e(the)h(curren)m(t)g(template)g(\014le)f(and)g(b)s(egin) g(reading)g(the)h(include)d(\014le.)54 b(Once)35 b(the)g(parser)f(reac) m(hes)i(the)0 1862 y(end)f(of)h(the)g(include)d(\014le)i(it)g(con)m (tin)m(ues)g(parsing)g(the)g(curren)m(t)h(template)g(\014le.)55 b(Include)34 b(\014les)h(can)h(b)s(e)f(nested,)0 1975 y(and)30 b(HDU)h(de\014nitions)d(can)i(span)g(m)m(ultiple)e(template)j (\014les.)0 2135 y(The)g(start)h(of)g(a)g(GR)m(OUP)h(de\014nition)c(is) i(denoted)h(with)e(the)i('group')g(directiv)m(e,)f(and)h(the)f(end)h (of)f(a)i(GR)m(OUP)0 2248 y(de\014nition)i(is)i(denoted)g(with)f(the)i ('end')f(directiv)m(e.)61 b(Eac)m(h)39 b(GR)m(OUP)e(con)m(tains)h(0)g (or)f(more)h(mem)m(b)s(er)f(blo)s(c)m(ks)0 2361 y(\(HDUs)44 b(or)f(GR)m(OUPs\).)79 b(Mem)m(b)s(er)42 b(blo)s(c)m(ks)h(of)g(t)m(yp)s (e)g(GR)m(OUP)g(can)g(con)m(tain)g(their)f(o)m(wn)h(mem)m(b)s(er)f(blo) s(c)m(ks.)0 2474 y(The)32 b(GR)m(OUP)g(de\014nition)e(itself)h(o)s (ccupies)h(one)g(FITS)g(\014le)f(HDU)i(of)f(sp)s(ecial)f(t)m(yp)s(e)h (\(GR)m(OUP)h(HDU\),)h(so)e(if)g(a)0 2587 y(template)f(sp)s(eci\014es)e (1)i(group)e(with)g(1)i(mem)m(b)s(er)f(HDU)h(lik)m(e:)0 2838 y Fe(\\group)0 2951 y(grpdescr)46 b(=)h('demo')0 3064 y(xtension)f(bintable)0 3177 y(#)h(this)g(bintable)f(has)h(0)g (cols,)f(0)i(rows)0 3290 y(\\end)0 3541 y Fj(then)30 b(the)h(parser)e(creates)j(a)f(FITS)f(\014le)f(with)g(3)i(HDUs)g(:)0 3792 y Fe(1\))47 b(dummy)g(PHDU)0 3905 y(2\))g(GROUP)g(HDU)f(\(has)h(1) h(member,)d(which)i(is)g(bintable)e(in)j(HDU)f(number)f(3\))0 4018 y(3\))h(bintable)f(\(member)g(of)h(GROUP)f(in)h(HDU)g(number)f (2\))0 4269 y Fj(T)-8 b(ec)m(hnically)29 b(sp)s(eaking,)g(the)g(GR)m (OUP)i(HDU)f(is)f(a)h(BINT)-8 b(ABLE)30 b(with)f(6)h(columns.)39 b(Applications)28 b(can)i(de\014ne)0 4382 y(additional)20 b(columns)h(in)f(a)j(GR)m(OUP)f(HDU)h(using)e(TF)m(ORMn)g(and)h(TTYPEn) f(\(where)g(n)h(is)f(7,)j(8,)h(....\))39 b(k)m(eyw)m(ords)0 4494 y(or)30 b(their)g(auto-indexing)f(equiv)-5 b(alen)m(ts.)0 4655 y(F)d(or)26 b(a)f(more)g(complicated)f(example)g(of)h(a)h (template)f(\014le)f(using)f(the)i(group)f(directiv)m(es,)i(lo)s(ok)e (at)h(the)g(sample.tpl)0 4767 y(\014le)k(that)i(is)f(included)d(in)j (the)g(CFITSIO)f(distribution.)0 5100 y Ff(11.4)136 b(F)-11 b(ormal)45 b(T)-11 b(emplate)46 b(Syn)l(tax)0 5350 y Fj(The)30 b(template)h(syn)m(tax)g(can)f(formally)f(b)s(e)h(de\014ned)f (as)i(follo)m(ws:)191 5601 y Fe(TEMPLATE)45 b(=)j(BLOCK)e([)i(BLOCK)e (...)h(])p eop %%Page: 134 142 134 141 bop 0 299 a Fj(134)2250 b Fh(CHAPTER)29 b(11.)72 b(TEMPLA)-8 b(TE)30 b(FILES)334 555 y Fe(BLOCK)46 b(=)i({)f(HDU)g(|)h (GROUP)e(})334 781 y(GROUP)g(=)i(\\GROUP)e([)h(BLOCK)g(...)g(])g(\\END) 430 1007 y(HDU)f(=)i(XTENSION)d([)j(LINE)f(...)f(])i({)f(XTENSION)f(|)h (\\GROUP)f(|)i(\\END)f(|)g(EOF)g(})382 1233 y(LINE)f(=)i([)f(KEYWORD)f ([)i(=)f(])h(])f([)g(VALUE)g(])g([)h(/)f(COMMENT)f(])191 1458 y(X)h(...)238 b(-)48 b(X)f(can)g(be)g(present)f(1)h(or)h(more)e (times)191 1571 y({)h(X)h(|)f(Y)h(})f(-)h(X)f(or)g(Y)191 1684 y([)g(X)h(])238 b(-)48 b(X)f(is)g(optional)0 1937 y Fj(A)m(t)34 b(the)f(topmost)g(lev)m(el,)g(the)g(template)h(de\014nes) d(1)j(or)e(more)h(template)g(blo)s(c)m(ks.)48 b(Blo)s(c)m(ks)33 b(can)g(b)s(e)f(either)g(HDU)0 2050 y(\(Header)27 b(Data)h(Unit\))f(or) f(a)h(GR)m(OUP)-8 b(.)28 b(F)-8 b(or)27 b(eac)m(h)g(blo)s(c)m(k)f(the)h (parser)f(creates)i(1)f(\(or)g(more)f(for)h(GR)m(OUPs\))g(FITS)0 2163 y(\014le)i(HDUs.)0 2495 y Ff(11.5)136 b(Errors)0 2745 y Fj(In)24 b(general)g(the)g(\014ts)p 692 2745 28 4 v 33 w(execute)p 1019 2745 V 34 w(template\(\))h(function)e(tries)h (to)h(b)s(e)f(as)g(atomic)h(as)g(p)s(ossible,)e(so)h(either)g(ev)m (erything)0 2858 y(is)f(done)h(or)g(nothing)e(is)h(done.)39 b(If)23 b(an)h(error)f(o)s(ccurs)h(during)e(parsing)g(of)i(the)g (template,)i(\014ts)p 3125 2858 V 33 w(execute)p 3452 2858 V 34 w(template\(\))0 2971 y(will)i(\(try)j(to\))h(delete)f(the)g (top)g(lev)m(el)f(BLOCK)g(\(with)g(all)f(its)i(c)m(hildren)d(if)i(an)m (y\))h(in)f(whic)m(h)f(the)i(error)f(o)s(ccurred,)0 3084 y(then)g(it)g(will)e(stop)i(reading)g(the)g(template)h(\014le)e(and)h (it)g(will)e(return)h(with)g(an)h(error.)0 3417 y Ff(11.6)136 b(Examples)0 3667 y Fj(1.)54 b(This)33 b(template)i(\014le)f(will)e (create)k(a)f(200)h(x)e(300)i(pixel)d(image,)k(with)c(4-b)m(yte)j(in)m (teger)f(pixel)e(v)-5 b(alues,)35 b(in)f(the)0 3780 y(primary)28 b(HDU:)95 4032 y Fe(SIMPLE)47 b(=)g(T)95 4145 y(BITPIX)g(=)g(32)95 4258 y(NAXIS)g(=)g(2)239 b(/)47 b(number)f(of)h(dimensions)95 4371 y(NAXIS1)g(=)g(100)95 b(/)47 b(length)f(of)h(first)g(axis)95 4484 y(NAXIS2)g(=)g(200)95 b(/)47 b(length)f(of)h(second)f(axis)95 4597 y(OBJECT)h(=)g(NGC)g(253)g(/)g(name)g(of)g(observed)f(object)0 4850 y Fj(The)35 b(allo)m(w)m(ed)g(v)-5 b(alues)35 b(of)g(BITPIX)g(are) h(8,)h(16,)h(32,)g(-32,)g(or)d(-64,)j(represen)m(ting,)e(resp)s(ectiv)m (ely)-8 b(,)37 b(8-bit)e(in)m(teger,)0 4962 y(16-bit)c(in)m(teger,)g (32-bit)f(in)m(teger,)h(32-bit)g(\015oating)f(p)s(oin)m(t,)g(or)g(64)h (bit)f(\015oating)g(p)s(oin)m(t)f(pixels.)0 5123 y(2.)39 b(T)-8 b(o)23 b(create)h(a)f(FITS)e(table,)k(the)d(template)h(\014rst)f (needs)g(to)i(include)c(XTENSION)i(=)g(T)-8 b(ABLE)23 b(or)f(BINT)-8 b(ABLE)0 5235 y(to)31 b(de\014ne)e(whether)g(it)g(is)g (an)g(ASCI)s(I)g(or)g(binary)f(table,)i(and)g(NAXIS2)g(to)g(de\014ne)f (the)h(n)m(um)m(b)s(er)f(of)h(ro)m(ws)f(in)g(the)0 5348 y(table.)49 b(Tw)m(o)34 b(template)f(lines)f(are)i(then)f(needed)f(to)i (de\014ne)f(the)g(name)h(\(TTYPEn\))e(and)h(FITS)g(data)h(format)0 5461 y(\(TF)m(ORMn\))d(of)f(the)h(columns,)e(as)i(in)e(this)g(example:) 95 5714 y Fe(xtension)46 b(=)h(bintable)p eop %%Page: 135 143 135 142 bop 0 299 a Fh(11.6.)73 b(EXAMPLES)2993 b Fj(135)95 555 y Fe(naxis2)47 b(=)g(40)95 668 y(ttype#)g(=)g(Name)95 781 y(tform#)g(=)g(10a)95 894 y(ttype#)g(=)g(Npoints)95 1007 y(tform#)g(=)g(j)95 1120 y(ttype#)g(=)g(Rate)95 1233 y(tunit#)g(=)g(counts/s)95 1346 y(tform#)g(=)g(e)0 1605 y Fj(The)26 b(ab)s(o)m(v)m(e)j(example)d(de\014nes)g(a)i(n)m(ull)d (primary)g(arra)m(y)i(follo)m(w)m(ed)g(b)m(y)g(a)g(40-ro)m(w)h(binary)d (table)i(extension)g(with)f(3)0 1718 y(columns)h(called)g('Name',)j ('Np)s(oin)m(ts',)e(and)g('Rate',)i(with)d(data)i(formats)f(of)g('10A') i(\(ASCI)s(I)d(c)m(haracter)i(string\),)0 1831 y('1J')k(\(in)m(teger\)) h(and)e('1E')i(\(\015oating)e(p)s(oin)m(t\),)h(resp)s(ectiv)m(ely)-8 b(.)48 b(Note)34 b(that)f(the)g(other)g(required)e(FITS)h(k)m(eyw)m (ords)0 1944 y(\(BITPIX,)37 b(NAXIS,)g(NAXIS1,)h(PCOUNT,)e(GCOUNT,)h (TFIELDS,)f(and)g(END\))h(do)g(not)g(need)f(to)h(b)s(e)f(ex-)0 2057 y(plicitly)f(de\014ned)h(in)h(the)g(template)h(b)s(ecause)g(their) f(v)-5 b(alues)37 b(can)h(b)s(e)f(inferred)e(from)j(the)f(other)h(k)m (eyw)m(ords)g(in)0 2170 y(the)d(template.)54 b(This)33 b(example)i(also)g(illustrates)d(that)k(the)f(templates)g(are)g (generally)f(case-insensitiv)m(e)g(\(the)0 2283 y(k)m(eyw)m(ord)29 b(names)g(and)g(TF)m(ORMn)f(v)-5 b(alues)29 b(are)g(con)m(v)m(erted)i (to)e(upp)s(er-case)g(in)e(the)i(FITS)g(\014le\))f(and)g(that)i(string) 0 2396 y(k)m(eyw)m(ord)h(v)-5 b(alues)30 b(generally)f(do)h(not)h(need) f(to)h(b)s(e)f(enclosed)g(in)f(quotes.)p eop %%Page: 136 144 136 143 bop 0 299 a Fj(136)2250 b Fh(CHAPTER)29 b(11.)72 b(TEMPLA)-8 b(TE)30 b(FILES)p eop %%Page: 137 145 137 144 bop 0 1225 a Fg(Chapter)65 b(12)0 1687 y Fm(Lo)6 b(cal)78 b(FITS)e(Con)-6 b(v)g(en)g(tions)0 2180 y Fj(CFITSIO)25 b(supp)s(orts)g(sev)m(eral)i(lo)s(cal)e(FITS)h(con)m(v)m(en)m(tions)i (whic)m(h)d(are)i(not)g(de\014ned)e(in)g(the)i(o\016cial)f(NOST)g(FITS) 0 2293 y(standard)k(and)g(whic)m(h)g(are)h(not)g(necessarily)e (recognized)i(or)g(supp)s(orted)e(b)m(y)i(other)g(FITS)f(soft)m(w)m (are)i(pac)m(k)-5 b(ages.)0 2406 y(Programmers)36 b(should)e(b)s(e)h (cautious)h(ab)s(out)f(using)g(these)h(features,)i(esp)s(ecially)c(if)h (the)h(FITS)f(\014les)g(that)i(are)0 2518 y(pro)s(duced)31 b(are)i(exp)s(ected)g(to)g(b)s(e)f(pro)s(cessed)g(b)m(y)h(other)f(soft) m(w)m(are)i(systems)f(whic)m(h)e(do)i(not)f(use)h(the)f(CFITSIO)0 2631 y(in)m(terface.)0 3275 y Ff(12.1)136 b(64-Bit)45 b(Long)g(In)l(tegers)0 3587 y Fj(CFITSIO)38 b(can)i(read)f(and)g(write) g(FITS)f(images)i(or)g(table)f(columns)f(con)m(taining)h(64-bit)h(in)m (teger)g(data)g(v)-5 b(al-)0 3700 y(ues.)63 b(This)37 b(data)h(t)m(yp)s(e)g(is)f(not)i(recognized)f(in)f(the)h(o\016cial)f (FITS)h(Standard)e(de\014nition)g(do)s(cumen)m(t,)k(but)d(it)0 3813 y(is)31 b(lik)m(ely)f(that)i(FITS)f(will)e(ev)m(en)m(tually)i (supp)s(ort)f(this)h(data)h(t)m(yp)s(e,)g(esp)s(ecially)e(as)i (computers)f(that)i(run)d(64-bit)0 3926 y(op)s(erating)25 b(systems)h(b)s(ecome)f(more)h(common.)40 b(Supp)s(ort)23 b(for)i(reading)g(and)g(writing)e(64-bit)j(in)m(tegers)g(in)e(CFIT-)0 4039 y(SIO)32 b(can)i(b)s(e)f(con)m(trolled)g(with)f(the)i(#de\014ne)e (statemen)m(t)k(at)e(the)g(b)s(eginning)d(of)i(the)h(\014tsio2.h)f (\014le)f(b)m(y)i(setting)0 4152 y(SUPPOR)-8 b(T)p 444 4152 28 4 v 32 w(64BIT)p 729 4152 V 33 w(INTEGERS)30 b(to)h(1)g(\(enable\))f(or)h(0)f(\(disable\).)0 4312 y(Under)k(the)h(con)m(v)m(en)m(tion)h(used)e(b)m(y)h(CFITSIO,)e(FITS)h (64-bit)h(images)g(ha)m(v)m(e)h(BITPIX)f(=)f(64,)j(and)e(the)g(64-bit)0 4425 y(binary)e(table)i(columns)e(ha)m(v)m(e)j(TF)m(ORMn)f(=)f('K'.)i (The)e(use)g(of)h(these)h(data)f(t)m(yp)s(es)g(on)g(platforms)e(where)i (the)0 4538 y(size)26 b(of)h(a)g('long')f(\(or)h('longlong'\))g(in)m (teger)g(=)f(8)h(b)m(ytes)g(is)e(rather)i(in)m(tuitiv)m(e.)38 b(CFITSIO)25 b(will)e(write)j(64-bit)h('long')0 4650 y(v)-5 b(ariable)29 b(v)-5 b(alues)30 b(to)g(the)h(FITS)e(\014le)h(and) f(read)h(them)g(bac)m(k)h(in)m(to)g('long')f(v)-5 b(ariables)29 b(just)g(as)i(one)f(w)m(ould)f(exp)s(ect.)0 4763 y(CFITSIO)j(also)h (supp)s(orts)f(implicit)e(data)k(t)m(yp)s(e)g(con)m(v)m(ersion)f(b)s (et)m(w)m(een)i(64-bit)e(in)m(teger)h(images)f(and)g(columns)0 4876 y(and)24 b(an)m(y)h(other)f(supp)s(orted)f(data)i(t)m(yp)s(e,)h (although)e(some)h(loss)f(of)g(n)m(umerical)f(precision)g(or)i(n)m (umerical)e(o)m(v)m(er\015o)m(w)0 4989 y(is)29 b(lik)m(ely)g(in)g(this) h(case.)0 5149 y(The)h(situation)f(is)h(more)g(di\016cult)e(on)j (32-bit)f(computing)g(platforms)f(that)i(do)f(not)h(supp)s(ort)e(an)h (in)m(trinsic)e(64-)0 5262 y(bit)37 b(in)m(teger)i(data)g(t)m(yp)s(e.) 65 b(In)38 b(this)f(case)i(it)f(is)f(not)i(p)s(ossible)d(to)j(return)e (the)i(full)d(64)j(precision)e(of)h(the)h(FITS)0 5375 y(data)29 b(v)-5 b(alues)27 b(when)g(reading)g(the)i(v)-5 b(alues)27 b(in)m(to)h(a)g(program)g(v)-5 b(ariable.)39 b(CFITSIO)26 b(will)g(still)g(con)m(v)m(ert)j(the)g(64-bit)0 5488 y(in)m(teger)d(v)-5 b(alues)25 b(in)m(to)g(an)m(y)h(other)g(supp)s (orted)e(data)i(t)m(yp)s(e;)i(the)d(64-bit)h(double)e(data)j(t)m(yp)s (e)e(is)g(probably)f(the)i(most)0 5601 y(useful)33 b(in)g(this)h(case.) 55 b(It)35 b(only)f(pro)m(vides)f(ab)s(out)i(52-bits)g(of)g(precision)e (in)g(the)i(man)m(tissa,)h(ho)m(w)m(ev)m(er,)i(so)d(some)0 5714 y(lose)30 b(of)h(precision)d(is)i(p)s(ossible.)1882 5942 y(137)p eop %%Page: 138 146 138 145 bop 0 299 a Fj(138)1741 b Fh(CHAPTER)30 b(12.)112 b(LOCAL)29 b(FITS)h(CONVENTIONS)0 555 y Ff(12.2)136 b(Long)44 b(String)i(Keyw)l(ord)f(V)-11 b(alues.)0 805 y Fj(The)43 b(length)h(of)g(a)g(standard)g(FITS)f(string)g(k)m(eyw)m(ord)h(is)f (limited)f(to)j(68)f(c)m(haracters)i(b)s(ecause)e(it)f(m)m(ust)h(\014t) 0 918 y(en)m(tirely)33 b(within)e(a)j(single)f(FITS)g(header)g(k)m(eyw) m(ord)i(record.)50 b(In)33 b(some)i(instances)e(it)g(is)g(necessary)h (to)h(enco)s(de)0 1031 y(strings)28 b(longer)i(than)f(this)f(limit,)g (so)i(CFITSIO)e(supp)s(orts)g(a)h(lo)s(cal)g(con)m(v)m(en)m(tion)i(in)d (whic)m(h)h(the)g(string)g(v)-5 b(alue)29 b(is)0 1144 y(con)m(tin)m(ued)35 b(o)m(v)m(er)h(m)m(ultiple)c(k)m(eyw)m(ords.)55 b(This)33 b(con)m(tin)m(uation)h(con)m(v)m(en)m(tion)i(uses)f(an)f(amp) s(ersand)g(c)m(haracter)i(at)0 1257 y(the)26 b(end)f(of)h(eac)m(h)g (substring)e(to)i(indicate)f(that)h(it)g(is)e(con)m(tin)m(ued)i(on)f (the)h(next)g(k)m(eyw)m(ord,)h(and)e(the)h(con)m(tin)m(uation)0 1370 y(k)m(eyw)m(ords)40 b(all)f(ha)m(v)m(e)i(the)f(name)g(CONTINUE)f (without)g(an)h(equal)f(sign)g(in)g(column)g(9.)69 b(The)40 b(string)e(v)-5 b(alue)0 1483 y(ma)m(y)33 b(b)s(e)f(con)m(tin)m(ued)g (in)g(this)f(w)m(a)m(y)i(o)m(v)m(er)h(as)f(man)m(y)g(additional)d (CONTINUE)i(k)m(eyw)m(ords)h(as)f(is)g(required.)45 b(The)0 1596 y(follo)m(wing)34 b(lines)f(illustrate)g(this)h(con)m(tin)m (uation)h(con)m(v)m(en)m(tion)i(whic)m(h)c(is)i(used)f(in)g(the)h(v)-5 b(alue)35 b(of)g(the)g(STRKEY)0 1709 y(k)m(eyw)m(ord:)0 1939 y Fe(LONGSTRN=)45 b('OGIP)i(1.0')189 b(/)48 b(The)f(OGIP)f(Long)h (String)f(Convention)f(may)i(be)g(used.)0 2051 y(STRKEY)94 b(=)47 b('This)g(is)g(a)g(very)g(long)g(string)f(keyword&')93 b(/)47 b(Optional)f(Comment)0 2164 y(CONTINUE)93 b(')48 b(value)e(that)h(is)g(continued)e(over)i(3)g(keywords)f(in)h(the)g(&)95 b(')0 2277 y(CONTINUE)e('FITS)47 b(header.')e(/)j(This)e(is)h(another)f (optional)g(comment.)0 2507 y Fj(It)29 b(is)f(recommended)g(that)h(the) g(LONGSTRN)f(k)m(eyw)m(ord,)i(as)f(sho)m(wn)f(here,)h(alw)m(a)m(ys)h(b) s(e)e(included)e(in)h(an)m(y)i(HDU)0 2620 y(that)i(uses)f(this)f (longstring)g(con)m(v)m(en)m(tion)j(as)f(a)f(w)m(arning)g(to)h(an)m(y)g (soft)m(w)m(are)g(that)g(m)m(ust)g(read)f(the)h(k)m(eyw)m(ords.)41 b(A)0 2733 y(routine)c(called)f(\014ts)p 712 2733 28 4 v 33 w(write)p 948 2733 V 32 w(k)m(ey)p 1113 2733 V 33 w(longw)m(arn)h(has)g(b)s(een)g(pro)m(vided)f(in)h(CFITSIO)e(to)k (write)d(this)h(k)m(eyw)m(ord)h(if)e(it)0 2846 y(do)s(es)30 b(not)h(already)f(exist.)0 3006 y(This)f(long)h(string)f(con)m(v)m(en)m (tion)i(is)f(supp)s(orted)e(b)m(y)j(the)f(follo)m(wing)f(CFITSIO)g (routines:)191 3236 y Fe(fits_write_key_longstr)89 b(-)48 b(write)e(a)i(long)e(string)g(keyword)g(value)191 3349 y(fits_insert_key_longstr)41 b(-)48 b(insert)e(a)h(long)g(string)f (keyword)g(value)191 3462 y(fits_modify_key_longstr)41 b(-)48 b(modify)e(a)h(long)g(string)f(keyword)g(value)191 3575 y(fits_update_key_longstr)41 b(-)48 b(modify)e(a)h(long)g(string)f (keyword)g(value)191 3688 y(fits_read_key_longstr)137 b(-)48 b(read)94 b(a)48 b(long)e(string)g(keyword)g(value)191 3801 y(fits_delete_key)425 b(-)48 b(delete)e(a)h(keyword)0 4030 y Fj(The)36 b(\014ts)p 320 4030 V 32 w(read)p 524 4030 V 33 w(k)m(ey)p 690 4030 V 34 w(longstr)f(routine)h(is)f(unique)f (among)j(all)f(the)g(CFITSIO)f(routines)g(in)g(that)i(it)f(in)m (ternally)0 4143 y(allo)s(cates)e(memory)f(for)h(the)f(long)g(string)g (v)-5 b(alue;)35 b(all)d(the)i(other)g(CFITSIO)e(routines)g(that)i (deal)f(with)g(arra)m(ys)0 4256 y(require)38 b(that)i(the)g(calling)e (program)h(pre-allo)s(cate)h(adequate)g(space)g(to)g(hold)e(the)i(arra) m(y)g(of)f(data.)69 b(Conse-)0 4369 y(quen)m(tly)-8 b(,)30 b(programs)g(whic)m(h)f(use)h(the)g(\014ts)p 1443 4369 V 32 w(read)p 1647 4369 V 33 w(k)m(ey)p 1813 4369 V 34 w(longstr)f(routine)g(m)m(ust)h(b)s(e)g(careful)f(to)i(free)g(the)f (allo)s(cated)0 4482 y(memory)g(for)g(the)h(string)e(when)h(it)g(is)f (no)h(longer)g(needed.)0 4642 y(The)g(follo)m(wing)f(2)h(routines)g (also)g(ha)m(v)m(e)i(limited)c(supp)s(ort)g(for)i(this)g(long)g(string) f(con)m(v)m(en)m(tion,)286 4872 y Fe(fits_modify_key_str)43 b(-)k(modify)f(an)i(existing)d(string)h(keyword)g(value)286 4985 y(fits_update_key_str)d(-)k(update)f(a)i(string)e(keyword)g(value) 0 5215 y Fj(in)23 b(that)i(they)f(will)e(correctly)i(o)m(v)m(erwrite)h (an)f(existing)f(long)h(string)f(v)-5 b(alue,)26 b(but)d(the)h(new)g (string)f(v)-5 b(alue)24 b(is)f(limited)0 5328 y(to)31 b(a)g(maxim)m(um)e(of)i(68)g(c)m(haracters)h(in)d(length.)0 5488 y(The)g(more)h(commonly)g(used)f(CFITSIO)f(routines)h(to)h(write)f (string)g(v)-5 b(alued)29 b(k)m(eyw)m(ords)h(\(\014ts)p 3254 5488 V 33 w(up)s(date)p 3563 5488 V 32 w(k)m(ey)h(and)0 5601 y(\014ts)p 127 5601 V 32 w(write)p 362 5601 V 32 w(k)m(ey\))j(do)e(not)h(supp)s(ort)d(this)h(long)h(string)g(con)m(v)m (en)m(tion)h(and)f(only)f(supp)s(ort)g(strings)g(up)g(to)i(68)g(c)m (har-)0 5714 y(acters)g(in)e(length.)47 b(This)30 b(has)i(b)s(een)g (done)g(delib)s(erately)e(to)j(prev)m(en)m(t)g(programs)f(from)g(inadv) m(erten)m(tly)g(writing)p eop %%Page: 139 147 139 146 bop 0 299 a Fh(12.3.)73 b(ARRA)-8 b(YS)30 b(OF)h(FIXED-LENGTH)g (STRINGS)e(IN)h(BINAR)-8 b(Y)32 b(T)-8 b(ABLES)871 b Fj(139)0 555 y(k)m(eyw)m(ords)25 b(using)e(this)h(non-standard)f(con)m (v)m(en)m(tion)j(without)e(the)h(explicit)e(in)m(ten)m(t)i(of)g(the)f (programmer)h(or)f(user.)0 668 y(The)36 b(\014ts)p 320 668 28 4 v 32 w(write)p 555 668 V 32 w(k)m(ey)p 720 668 V 34 w(longstr)g(routine)f(m)m(ust)i(b)s(e)f(called)g(instead)f(to)j (write)d(long)h(strings.)58 b(This)35 b(routine)h(can)0 781 y(also)30 b(b)s(e)g(used)g(to)h(write)e(ordinary)g(string)g(v)-5 b(alues)30 b(less)g(than)g(68)h(c)m(haracters)h(in)d(length.)0 1128 y Ff(12.3)136 b(Arra)l(ys)45 b(of)g(Fixed-Length)g(Strings)g(in)g (Binary)f(T)-11 b(ables)0 1381 y Fj(The)29 b(de\014nition)e(of)j(the)f (FITS)g(binary)e(table)j(extension)f(format)g(do)s(es)h(not)f(pro)m (vide)g(a)g(simple)f(w)m(a)m(y)i(to)g(sp)s(ecify)0 1494 y(that)24 b(a)f(c)m(haracter)i(column)d(con)m(tains)h(an)g(arra)m(y)h (of)f(\014xed-length)f(strings.)37 b(T)-8 b(o)24 b(supp)s(ort)d(this)h (feature,)j(CFITSIO)0 1607 y(uses)31 b(a)h(lo)s(cal)f(con)m(v)m(en)m (tion)h(for)f(the)h(format)g(of)g(the)f(TF)m(ORMn)g(k)m(eyw)m(ord)h(v) -5 b(alue)31 b(of)h(the)g(form)f('rAw')g(where)g('r')0 1720 y(is)c(an)g(in)m(teger)h(sp)s(ecifying)d(the)j(total)g(width)e(in) g(c)m(haracters)j(of)f(the)g(column,)f(and)g('w')g(is)g(an)g(in)m (teger)h(sp)s(ecifying)0 1833 y(the)c(\(\014xed\))g(length)g(of)g(an)g (individual)19 b(unit)k(string)g(within)e(the)j(v)m(ector.)41 b(F)-8 b(or)24 b(example,)i(TF)m(ORM1)e(=)g('120A10')0 1946 y(w)m(ould)k(indicate)g(that)h(the)h(binary)d(table)i(column)f(is) g(120)i(c)m(haracters)g(wide)e(and)h(consists)f(of)h(12)h(10-c)m (haracter)0 2059 y(length)c(strings.)38 b(This)24 b(con)m(v)m(en)m (tion)k(is)d(recognized)i(b)m(y)f(the)g(CFITSIO)f(routines)g(that)i (read)f(or)h(write)e(strings)g(in)0 2171 y(binary)30 b(tables.)44 b(The)31 b(Binary)g(T)-8 b(able)31 b(de\014nition)e(do)s (cumen)m(t)i(sp)s(eci\014es)g(that)h(other)g(optional)e(c)m(haracters)j (ma)m(y)0 2284 y(follo)m(w)f(the)h(data)g(t)m(yp)s(e)g(co)s(de)g(in)e (the)i(TF)m(ORM)g(k)m(eyw)m(ord,)h(so)f(this)e(lo)s(cal)h(con)m(v)m(en) m(tion)i(is)e(in)f(compliance)h(with)0 2397 y(the)f(FITS)e(standard)h (although)g(other)g(FITS)g(readers)g(ma)m(y)h(not)g(recognize)g(this)e (con)m(v)m(en)m(tion.)0 2557 y(The)c(Binary)g(T)-8 b(able)26 b(de\014nition)d(do)s(cumen)m(t)j(that)h(w)m(as)f(appro)m(v)m(ed)g(b)m (y)g(the)g(IA)m(U)g(in)f(1994)j(con)m(tains)e(an)f(app)s(endix)0 2670 y(describing)20 b(an)j(alternate)g(con)m(v)m(en)m(tion)h(for)f(sp) s(ecifying)d(arra)m(ys)j(of)g(\014xed)f(or)h(v)-5 b(ariable)22 b(length)g(strings)f(in)h(a)h(binary)0 2783 y(table)34 b(c)m(haracter)h(column)e(\(with)g(the)i(form)e('rA:SSTRw/nnn\)'.)50 b(This)32 b(app)s(endix)f(w)m(as)k(not)f(o\016cially)f(v)m(oted)0 2896 y(on)d(b)m(y)h(the)f(IA)m(U)h(and)f(hence)g(is)g(still)e(pro)m (visional.)39 b(CFITSIO)29 b(do)s(es)h(not)g(curren)m(tly)g(supp)s(ort) e(this)i(prop)s(osal.)0 3243 y Ff(12.4)136 b(Keyw)l(ord)45 b(Units)h(Strings)0 3496 y Fj(One)37 b(limitation)f(of)h(the)h(curren)m (t)g(FITS)e(Standard)h(is)g(that)h(it)f(do)s(es)g(not)h(de\014ne)f(a)h (sp)s(eci\014c)e(con)m(v)m(en)m(tion)j(for)0 3609 y(recording)29 b(the)h(ph)m(ysical)f(units)g(of)h(a)g(k)m(eyw)m(ord)h(v)-5 b(alue.)40 b(The)30 b(TUNITn)f(k)m(eyw)m(ord)h(can)g(b)s(e)g(used)f(to) i(sp)s(ecify)e(the)0 3722 y(ph)m(ysical)34 b(units)g(of)h(the)h(v)-5 b(alues)35 b(in)f(a)h(table)h(column,)f(but)g(there)g(is)g(no)g (analogous)h(con)m(v)m(en)m(tion)g(for)f(k)m(eyw)m(ord)0 3835 y(v)-5 b(alues.)41 b(The)30 b(commen)m(t)h(\014eld)f(of)g(the)h(k) m(eyw)m(ord)g(is)f(often)h(used)f(for)g(this)f(purp)s(ose,)h(but)f(the) i(units)e(are)i(usually)0 3948 y(not)g(sp)s(eci\014ed)d(in)h(a)i(w)m (ell)e(de\014ned)h(format)g(that)h(FITS)f(readers)g(can)h(easily)e (recognize)i(and)f(extract.)0 4108 y(T)-8 b(o)27 b(solv)m(e)h(this)d (problem,)i(CFITSIO)e(uses)i(a)g(lo)s(cal)f(con)m(v)m(en)m(tion)i(in)e (whic)m(h)f(the)j(k)m(eyw)m(ord)f(units)e(are)j(enclosed)e(in)0 4221 y(square)20 b(brac)m(k)m(ets)j(as)e(the)f(\014rst)g(tok)m(en)i(in) e(the)g(k)m(eyw)m(ord)i(commen)m(t)f(\014eld;)i(more)e(sp)s (eci\014cally)-8 b(,)21 b(the)g(op)s(ening)e(square)0 4334 y(brac)m(k)m(et)28 b(immediately)d(follo)m(ws)g(the)i(slash)e('/') i(commen)m(t)h(\014eld)d(delimiter)f(and)i(a)g(single)f(space)i(c)m (haracter.)41 b(The)0 4447 y(follo)m(wing)29 b(examples)h(illustrate)e (k)m(eyw)m(ords)j(that)g(use)f(this)f(con)m(v)m(en)m(tion:)0 4718 y Fe(EXPOSURE=)713 b(1800.0)47 b(/)g([s])g(elapsed)f(exposure)f (time)0 4831 y(V_HELIO)h(=)763 b(16.23)47 b(/)g([km)g(s**\(-1\)])e (heliocentric)g(velocity)0 4944 y(LAMBDA)94 b(=)763 b(5400.)47 b(/)g([angstrom])e(central)h(wavelength)0 5057 y(FLUX)190 b(=)47 b(4.9033487787637465E-30)42 b(/)47 b([J/cm**2/s])e(average)h (flux)0 5328 y Fj(In)28 b(general,)g(the)h(units)d(named)i(in)f(the)i (IA)m(U\(1988\))i(St)m(yle)d(Guide)f(are)i(recommended,)f(with)f(the)i (main)e(excep-)0 5441 y(tion)j(that)h(the)f(preferred)g(unit)e(for)j (angle)f(is)f('deg')j(for)e(degrees.)0 5601 y(The)38 b(\014ts)p 322 5601 V 33 w(read)p 527 5601 V 33 w(k)m(ey)p 693 5601 V 33 w(unit)g(and)g(\014ts)p 1234 5601 V 32 w(write)p 1469 5601 V 32 w(k)m(ey)p 1634 5601 V 34 w(unit)f(routines)h (in)g(CFITSIO)f(read)i(and)f(write,)j(resp)s(ectiv)m(ely)-8 b(,)0 5714 y(the)31 b(k)m(eyw)m(ord)f(unit)f(strings)h(in)f(an)h (existing)f(k)m(eyw)m(ord.)p eop %%Page: 140 148 140 147 bop 0 299 a Fj(140)1741 b Fh(CHAPTER)30 b(12.)112 b(LOCAL)29 b(FITS)h(CONVENTIONS)0 555 y Ff(12.5)136 b(HIERAR)l(CH)46 b(Con)l(v)l(en)l(tion)g(for)f(Extended)h(Keyw)l(ord)f(Names)0 805 y Fj(CFITSIO)c(supp)s(orts)g(the)i(HIERAR)m(CH)g(k)m(eyw)m(ord)g (con)m(v)m(en)m(tion)h(whic)m(h)e(allo)m(ws)g(k)m(eyw)m(ord)h(names)g (that)h(are)0 918 y(longer)33 b(then)f(8)i(c)m(haracters)g(and)f(ma)m (y)h(con)m(tain)f(the)g(full)e(range)i(of)h(prin)m(table)d(ASCI)s(I)g (text)j(c)m(haracters.)51 b(This)0 1031 y(con)m(v)m(en)m(tion)38 b(w)m(as)g(dev)m(elop)s(ed)e(at)i(the)f(Europ)s(ean)f(Southern)g (Observ)-5 b(atory)37 b(\(ESO\))f(to)i(supp)s(ort)d(hierarc)m(hical)0 1144 y(FITS)30 b(k)m(eyw)m(ord)g(suc)m(h)h(as:)0 1395 y Fe(HIERARCH)46 b(ESO)g(INS)h(FOCU)g(POS)g(=)g(-0.00002500)e(/)j (Focus)e(position)0 1646 y Fj(Basically)-8 b(,)52 b(this)46 b(con)m(v)m(en)m(tion)j(uses)e(the)h(FITS)f(k)m(eyw)m(ord)h('HIERAR)m (CH')h(to)f(indicate)f(that)h(this)e(con)m(v)m(en-)0 1759 y(tion)e(is)f(b)s(eing)g(used,)k(then)d(the)g(actual)h(k)m(eyw)m (ord)f(name)h(\()p Fe('ESO)i(INS)f(FOCU)h(POS')c Fj(in)g(this)g (example\))h(b)s(e-)0 1872 y(gins)39 b(in)f(column)g(10)j(and)e(can)h (con)m(tain)f(an)m(y)h(prin)m(table)e(ASCI)s(I)g(text)j(c)m(haracters,) i(including)37 b(spaces.)68 b(The)0 1985 y(equals)43 b(sign)h(marks)f(the)h(end)g(of)g(the)g(k)m(eyw)m(ord)h(name)f(and)f (is)h(follo)m(w)m(ed)f(b)m(y)h(the)g(usual)f(v)-5 b(alue)44 b(and)f(com-)0 2098 y(men)m(t)31 b(\014elds)e(just)h(as)h(in)e (standard)h(FITS)g(k)m(eyw)m(ords.)41 b(F)-8 b(urther)30 b(details)g(of)h(this)e(con)m(v)m(en)m(tion)j(are)f(describ)s(ed)d(at)0 2211 y(h)m(ttp://arcdev.hq.eso.org/dicb/dicd/dic-1-1.4.h)m(tml)33 b(\(searc)m(h)f(for)e(HIERAR)m(CH\).)0 2371 y(This)42 b(con)m(v)m(en)m(tion)k(allo)m(ws)e(a)g(m)m(uc)m(h)h(broader)e(range)i (of)f(k)m(eyw)m(ord)h(names)f(than)h(is)e(allo)m(w)m(ed)h(b)m(y)g(the)h (FITS)0 2484 y(Standard.)40 b(Here)30 b(are)h(more)g(examples)f(of)g (suc)m(h)g(k)m(eyw)m(ords:)0 2735 y Fe(HIERARCH)46 b(LongKeyword)e(=)k (47.5)e(/)i(Keyword)e(has)h(>)g(8)g(characters,)e(and)i(mixed)f(case)0 2848 y(HIERARCH)g(XTE$TEMP)f(=)j(98.6)e(/)i(Keyword)d(contains)h(the)h ('$')g(character)0 2961 y(HIERARCH)f(Earth)g(is)h(a)h(star)e(=)i(F)f(/) h(Keyword)d(contains)h(embedded)f(spaces)0 3212 y Fj(CFITSIO)40 b(will)f(transparen)m(tly)i(read)h(and)f(write)f(these)j(k)m(eyw)m (ords,)i(so)d(application)e(programs)h(do)g(not)h(in)0 3325 y(general)32 b(need)g(to)h(kno)m(w)f(an)m(ything)g(ab)s(out)g(the) g(sp)s(eci\014c)f(implemen)m(tation)g(details)g(of)i(the)f(HIERAR)m(CH) g(con-)0 3438 y(v)m(en)m(tion.)49 b(In)32 b(particular,)h(application)e (programs)h(do)h(not)h(need)e(to)i(sp)s(ecify)e(the)h(`HIERAR)m(CH')h (part)f(of)g(the)0 3551 y(k)m(eyw)m(ord)g(name)f(when)g(reading)f(or)h (writing)f(k)m(eyw)m(ords)h(\(although)g(it)g(ma)m(y)h(b)s(e)f (included)d(if)j(desired\).)45 b(When)0 3664 y(writing)33 b(a)i(k)m(eyw)m(ord,)h(CFITSIO)d(\014rst)h(c)m(hec)m(ks)i(to)f(see)g (if)f(the)h(k)m(eyw)m(ord)g(name)f(is)g(legal)g(as)h(a)g(standard)f (FITS)0 3776 y(k)m(eyw)m(ord)k(\(no)g(more)f(than)h(8)g(c)m(haracters)h (long)e(and)g(con)m(taining)g(only)f(letters,)k(digits,)e(or)g(a)g(min) m(us)d(sign)i(or)0 3889 y(underscore\).)68 b(If)39 b(so)h(it)f(writes)g (it)g(as)g(a)h(standard)f(FITS)g(k)m(eyw)m(ord,)k(otherwise)c(it)g (uses)g(the)h(hierarc)m(h)e(con-)0 4002 y(v)m(en)m(tion)33 b(to)g(write)f(the)g(k)m(eyw)m(ord.)48 b(The)32 b(maxim)m(um)f(k)m(eyw) m(ord)i(name)f(length)g(is)g(67)h(c)m(haracters,)i(whic)m(h)c(lea)m(v)m (es)0 4115 y(only)c(1)i(space)g(for)f(the)h(v)-5 b(alue)28 b(\014eld.)38 b(A)29 b(more)f(practical)g(limit)e(is)i(ab)s(out)g(40)h (c)m(haracters,)i(whic)m(h)c(lea)m(v)m(es)i(enough)0 4228 y(ro)s(om)f(for)h(most)f(k)m(eyw)m(ord)h(v)-5 b(alues.)40 b(CFITSIO)27 b(returns)g(an)h(error)h(if)e(there)i(is)e(not)i(enough)f (ro)s(om)h(for)f(b)s(oth)g(the)0 4341 y(k)m(eyw)m(ord)k(name)f(and)f (the)i(k)m(eyw)m(ord)f(v)-5 b(alue)31 b(on)g(the)h(80-c)m(haracter)h (card,)f(except)g(for)f(string-v)-5 b(alued)30 b(k)m(eyw)m(ords)0 4454 y(whic)m(h)i(are)h(simply)d(truncated)j(so)g(that)h(the)f(closing) f(quote)i(c)m(haracter)g(falls)d(in)h(column)g(80.)49 b(In)32 b(the)h(curren)m(t)0 4567 y(implemen)m(tation,)28 b(CFITSIO)f(preserv)m(es)i(the)g(case)h(of)f(the)g(letters)g(when)f (writing)f(the)i(k)m(eyw)m(ord)g(name,)g(but)f(it)0 4680 y(is)c(case-insensitiv)m(e)g(when)g(reading)g(or)h(searc)m(hing)g(for)g (a)g(k)m(eyw)m(ord.)40 b(The)24 b(curren)m(t)h(implemen)m(tation)e (allo)m(ws)i(an)m(y)0 4793 y(ASCI)s(I)k(text)j(c)m(haracter)h(\(ASCI)s (I)c(32)j(to)f(ASCI)s(I)f(126\))i(in)e(the)h(k)m(eyw)m(ord)g(name)g (except)h(for)e(the)h('=')g(c)m(haracter.)0 4906 y(A)f(space)h(is)f (also)g(required)f(on)h(either)g(side)f(of)i(the)f(equal)g(sign.)0 5238 y Ff(12.6)136 b(Tile-Compressed)46 b(Image)g(F)-11 b(ormat)0 5488 y Fj(CFITSIO)36 b(supp)s(orts)f(a)j(con)m(v)m(en)m(tion) h(for)e(compressing)g(n-dimensional)d(images)j(and)g(storing)g(the)h (resulting)0 5601 y(b)m(yte)i(stream)g(in)e(a)i(v)-5 b(ariable-length)38 b(column)g(in)g(a)i(FITS)f(binary)e(table.)68 b(The)39 b(general)h(principle)c(used)i(in)0 5714 y(this)33 b(con)m(v)m(en)m(tion)j(is)d(to)i(\014rst)f(divide)e(the)j (n-dimensional)c(image)k(in)m(to)f(a)h(rectangular)f(grid)f(of)i (subimages)e(or)p eop %%Page: 141 149 141 148 bop 0 299 a Fh(12.6.)73 b(TILE-COMPRESSED)28 b(IMA)m(GE)j(F)m(ORMA)-8 b(T)1838 b Fj(141)0 555 y(`tiles'.)55 b(Eac)m(h)35 b(tile)g(is)f(then)h(compressed)g(as)g(a)h(con)m(tin)m (uous)f(blo)s(c)m(k)f(of)i(data,)h(and)e(the)g(resulting)e(compressed)0 668 y(b)m(yte)k(stream)h(is)e(stored)h(in)e(a)i(ro)m(w)g(of)g(a)h(v)-5 b(ariable)35 b(length)h(column)g(in)g(a)h(FITS)f(binary)f(table.)60 b(By)37 b(dividing)0 781 y(the)j(image)f(in)m(to)g(tiles)g(it)g(is)f (generally)h(p)s(ossible)e(to)j(extract)h(and)d(uncompress)g (subsections)h(of)g(the)h(image)0 894 y(without)c(ha)m(ving)h(to)h (uncompress)e(the)h(whole)f(image.)61 b(The)37 b(default)f(tiling)f (pattern)j(treats)g(eac)m(h)g(ro)m(w)f(of)h(a)0 1007 y(2-dimensional)33 b(image)i(\(or)g(higher)e(dimensional)f(cub)s(e\))j (as)g(a)g(tile,)h(suc)m(h)e(that)i(eac)m(h)g(tile)e(con)m(tains)h (NAXIS1)0 1120 y(pixels.)57 b(An)m(y)36 b(other)h(rectangular)f(tiling) f(pattern)h(ma)m(y)h(also)f(b)s(e)g(de\014ned.)58 b(In)35 b(the)i(case)g(of)g(relativ)m(ely)e(small)0 1233 y(images)j(it)g(ma)m (y)h(b)s(e)f(su\016cien)m(t)f(to)i(compress)f(the)h(en)m(tire)f(image)g (as)h(a)f(single)f(tile,)j(resulting)c(in)h(an)h(output)0 1346 y(binary)28 b(table)i(with)f(1)h(ro)m(w.)41 b(In)29 b(the)h(case)h(of)f(3-dimensional)e(data)j(cub)s(es,)e(it)h(ma)m(y)g(b) s(e)f(adv)-5 b(an)m(tageous)32 b(to)f(treat)0 1458 y(eac)m(h)i(plane)e (of)h(the)g(cub)s(e)f(as)h(a)g(separate)h(tile)e(if)g(application)f (soft)m(w)m(are)k(t)m(ypically)c(needs)i(to)g(access)i(the)e(cub)s(e)0 1571 y(on)e(a)h(plane)e(b)m(y)i(plane)e(basis.)0 1732 y(See)41 b(section)f(5.6)i(\\Image)f(Compression")e(for)h(more)h (information)e(on)h(using)f(this)g(tile-compressed)h(image)0 1844 y(format.)p eop %%Page: 142 150 142 149 bop 0 299 a Fj(142)1741 b Fh(CHAPTER)30 b(12.)112 b(LOCAL)29 b(FITS)h(CONVENTIONS)p eop %%Page: 143 151 143 150 bop 0 1225 a Fg(Chapter)65 b(13)0 1687 y Fm(Optimizing)76 b(Programs)0 2180 y Fj(CFITSIO)22 b(has)h(b)s(een)f(carefully)g (designed)g(to)i(obtain)f(the)g(highest)g(p)s(ossible)d(sp)s(eed)j (when)f(reading)g(and)h(writing)0 2293 y(FITS)33 b(\014les.)50 b(In)33 b(order)h(to)g(ac)m(hiev)m(e)h(the)f(b)s(est)g(p)s(erformance,) g(ho)m(w)m(ev)m(er,)i(application)d(programmers)g(m)m(ust)h(b)s(e)0 2406 y(careful)23 b(to)i(call)e(the)h(CFITSIO)f(routines)f (appropriately)h(and)g(in)g(an)g(e\016cien)m(t)i(sequence;)i (inappropriate)21 b(usage)0 2518 y(of)31 b(CFITSIO)d(routines)i(can)g (greatly)h(slo)m(w)f(do)m(wn)g(the)h(execution)f(sp)s(eed)g(of)g(a)h (program.)0 2679 y(The)f(maxim)m(um)g(p)s(ossible)e(I/O)j(sp)s(eed)f (of)h(CFITSIO)e(dep)s(ends)g(of)i(course)g(on)f(the)h(t)m(yp)s(e)g(of)g (computer)g(system)0 2791 y(that)g(it)e(is)g(running)e(on.)41 b(As)30 b(a)g(rough)g(guide,)f(the)h(curren)m(t)g(generation)g(of)g(w)m (orkstations)g(can)h(ac)m(hiev)m(e)g(sp)s(eeds)0 2904 y(of)k(2)g({)g(10)g(MB/s)h(when)e(reading)g(or)g(writing)f(FITS)h (images)h(and)f(similar,)f(or)i(sligh)m(tly)e(slo)m(w)m(er)i(sp)s(eeds) e(with)0 3017 y(FITS)c(binary)g(tables.)40 b(Reading)30 b(of)g(FITS)g(\014les)f(can)i(o)s(ccur)f(at)h(ev)m(en)f(higher)f(rates) i(\(30MB/s)i(or)d(more\))h(if)e(the)0 3130 y(FITS)d(\014le)g(is)f (still)g(cac)m(hed)j(in)d(system)i(memory)f(follo)m(wing)g(a)h (previous)e(read)h(or)h(write)f(op)s(eration)g(on)h(the)g(same)0 3243 y(\014le.)43 b(T)-8 b(o)32 b(more)g(accurately)g(predict)e(the)i (b)s(est)f(p)s(erformance)g(that)h(is)e(p)s(ossible)f(on)j(an)m(y)g (particular)d(system,)k(a)0 3356 y(diagnostic)f(program)h(called)f (\\sp)s(eed.c")h(is)f(included)e(with)i(the)h(CFITSIO)e(distribution)e (whic)m(h)j(can)h(b)s(e)f(run)0 3469 y(to)f(appro)m(ximately)f(measure) g(the)h(maxim)m(um)e(p)s(ossible)f(sp)s(eed)h(of)i(writing)d(and)i (reading)g(a)g(test)i(FITS)d(\014le.)0 3629 y(The)k(follo)m(wing)e(2)j (sections)f(pro)m(vide)g(some)g(bac)m(kground)g(on)h(ho)m(w)f(CFITSIO)f (in)m(ternally)f(manages)j(the)f(data)0 3742 y(I/O)g(and)g(describ)s (es)e(some)j(strategies)g(that)g(ma)m(y)g(b)s(e)e(used)h(to)h(optimize) e(the)i(pro)s(cessing)e(sp)s(eed)g(of)h(soft)m(w)m(are)0 3855 y(that)e(uses)f(CFITSIO.)0 4271 y Ff(13.1)136 b(Ho)l(w)45 b(CFITSIO)f(Manages)i(Data)g(I/O)0 4538 y Fj(Man)m(y)22 b(CFITSIO)e(op)s(erations)h(in)m(v)m(olv)m(e)h(transferring)e(only)h(a) h(small)e(n)m(um)m(b)s(er)h(of)h(b)m(ytes)g(to)g(or)g(from)f(the)h (FITS)f(\014le)0 4650 y(\(e.g,)31 b(reading)d(a)h(k)m(eyw)m(ord,)h(or)f (writing)e(a)i(ro)m(w)g(in)e(a)i(table\);)h(it)f(w)m(ould)e(b)s(e)h(v)m (ery)i(ine\016cien)m(t)e(to)h(ph)m(ysically)e(read)0 4763 y(or)32 b(write)g(suc)m(h)g(small)e(blo)s(c)m(ks)i(of)g(data)h (directly)e(in)g(the)h(FITS)g(\014le)f(on)h(disk,)g(therefore)g (CFITSIO)f(main)m(tains)0 4876 y(a)38 b(set)g(of)g(in)m(ternal)f (Input{Output)e(\(IO\))j(bu\013ers)f(in)f(RAM)i(memory)g(that)g(eac)m (h)h(con)m(tain)f(one)g(FITS)f(blo)s(c)m(k)0 4989 y(\(2880)27 b(b)m(ytes\))f(of)f(data.)40 b(Whenev)m(er)25 b(CFITSIO)f(needs)g(to)i (access)g(data)g(in)e(the)h(FITS)f(\014le,)i(it)e(\014rst)g(transfers)h (the)0 5102 y(FITS)30 b(blo)s(c)m(k)g(con)m(taining)g(those)h(b)m(ytes) g(in)m(to)f(one)h(of)f(the)h(IO)f(bu\013ers)f(in)g(memory)-8 b(.)42 b(The)30 b(next)g(time)g(CFITSIO)0 5215 y(needs)36 b(to)g(access)i(b)m(ytes)e(in)f(the)h(same)h(blo)s(c)m(k)e(it)h(can)g (then)g(go)h(to)f(the)h(fast)f(IO)f(bu\013er)g(rather)h(than)g(using)f (a)0 5328 y(m)m(uc)m(h)d(slo)m(w)m(er)h(system)f(disk)f(access)i (routine.)45 b(The)32 b(n)m(um)m(b)s(er)f(of)h(a)m(v)-5 b(ailable)32 b(IO)g(bu\013ers)f(is)g(determined)g(b)m(y)h(the)0 5441 y(NIOBUF)f(parameter)g(\(in)e(\014tsio2.h\))h(and)g(is)g(curren)m (tly)f(set)i(to)g(40)g(b)m(y)g(default.)0 5601 y(Whenev)m(er)24 b(CFITSIO)f(reads)g(or)h(writes)f(data)h(it)g(\014rst)f(c)m(hec)m(ks)i (to)g(see)f(if)f(that)h(blo)s(c)m(k)g(of)g(the)g(FITS)f(\014le)f(is)h (already)0 5714 y(loaded)32 b(in)m(to)g(one)g(of)g(the)g(IO)g (bu\013ers.)44 b(If)32 b(not,)h(and)e(if)g(there)h(is)f(an)h(empt)m(y)h (IO)e(bu\013er)g(a)m(v)-5 b(ailable,)32 b(then)g(it)g(will)1882 5942 y(143)p eop %%Page: 144 152 144 151 bop 0 299 a Fj(144)1876 b Fh(CHAPTER)30 b(13.)112 b(OPTIMIZING)29 b(PR)m(OGRAMS)0 555 y Fj(load)j(that)i(blo)s(c)m(k)e (in)m(to)g(the)h(IO)g(bu\013er)e(\(when)h(reading)g(a)h(FITS)f (\014le\))g(or)h(will)d(initialize)g(a)j(new)f(blo)s(c)m(k)h(\(when)0 668 y(writing)i(to)j(a)g(FITS)f(\014le\).)61 b(If)37 b(all)f(the)i(IO)e(bu\013ers)h(are)g(already)g(full,)g(it)g(m)m(ust)h (decide)e(whic)m(h)g(one)i(to)g(reuse)0 781 y(\(generally)32 b(the)h(one)g(that)g(has)f(b)s(een)g(accessed)i(least)e(recen)m(tly\),) i(and)e(\015ush)f(the)i(con)m(ten)m(ts)h(bac)m(k)g(to)f(disk)e(if)g(it) 0 894 y(has)f(b)s(een)g(mo)s(di\014ed)e(b)s(efore)i(loading)f(the)i (new)f(blo)s(c)m(k.)0 1054 y(The)g(one)g(ma)5 b(jor)30 b(exception)h(to)g(the)f(ab)s(o)m(v)m(e)h(pro)s(cess)f(o)s(ccurs)g (whenev)m(er)g(a)g(large)h(con)m(tiguous)f(set)h(of)f(b)m(ytes)h(are)0 1167 y(accessed,)37 b(as)d(migh)m(t)h(o)s(ccur)f(when)f(reading)h(or)g (writing)e(a)j(FITS)f(image.)53 b(In)34 b(this)f(case)i(CFITSIO)e(b)m (ypasses)0 1280 y(the)i(in)m(ternal)f(IO)h(bu\013ers)f(and)g(simply)f (reads)i(or)g(writes)g(the)g(desired)f(b)m(ytes)h(directly)f(in)g(the)h (disk)f(\014le)g(with)0 1393 y(a)j(single)e(call)g(to)i(a)g(lo)m(w-lev) m(el)f(\014le)f(read)h(or)h(write)e(routine.)57 b(The)36 b(minim)m(um)e(threshold)g(for)i(the)h(n)m(um)m(b)s(er)e(of)0 1506 y(b)m(ytes)40 b(to)g(read)f(or)g(write)f(this)h(w)m(a)m(y)h(is)e (set)i(b)m(y)f(the)g(MINDIRECT)g(parameter)h(and)e(is)h(curren)m(tly)f (set)i(to)g(3)0 1619 y(FITS)28 b(blo)s(c)m(ks)f(=)h(8640)i(b)m(ytes.)41 b(This)27 b(is)g(the)h(most)h(e\016cien)m(t)g(w)m(a)m(y)g(to)g(read)g (or)f(write)g(large)g(c)m(h)m(unks)g(of)g(data)i(and)0 1732 y(can)37 b(ac)m(hiev)m(e)h(IO)e(transfer)g(rates)h(of)g(5)g({)g (10MB/s)i(or)d(greater.)61 b(Note)38 b(that)f(this)f(fast)h(direct)f (IO)g(pro)s(cess)g(is)0 1844 y(not)29 b(applicable)d(when)h(accessing)i (columns)f(of)g(data)h(in)e(a)i(FITS)f(table)g(b)s(ecause)h(the)f(b)m (ytes)h(are)g(generally)f(not)0 1957 y(con)m(tiguous)h(since)f(they)h (are)h(in)m(terlea)m(v)m(ed)f(b)m(y)g(the)g(other)g(columns)f(of)h (data)g(in)f(the)h(table.)40 b(This)27 b(explains)g(wh)m(y)0 2070 y(the)k(sp)s(eed)e(for)h(accessing)h(FITS)f(tables)g(is)f (generally)h(slo)m(w)m(er)g(than)h(accessing)f(FITS)g(images.)0 2230 y(Giv)m(en)h(this)g(bac)m(kground)g(information,)f(the)i(general)f (strategy)i(for)e(e\016cien)m(tly)g(accessing)h(FITS)f(\014les)f (should)0 2343 y(b)s(e)f(apparen)m(t:)41 b(when)28 b(dealing)h(with)f (FITS)h(images,)h(read)f(or)h(write)f(large)g(c)m(h)m(unks)h(of)g(data) g(at)g(a)g(time)f(so)h(that)0 2456 y(the)25 b(direct)f(IO)g(mec)m (hanism)f(will)f(b)s(e)i(in)m(v)m(ok)m(ed;)j(when)d(accessing)h(FITS)f (headers)g(or)g(FITS)g(tables,)i(on)e(the)h(other)0 2569 y(hand,)35 b(once)g(a)g(particular)e(FITS)h(blo)s(c)m(k)h(has)f(b)s (een)g(loading)g(in)m(to)g(one)h(of)g(the)g(IO)f(bu\013ers,)h(try)g(to) g(access)h(all)0 2682 y(the)30 b(needed)g(information)e(in)h(that)h (blo)s(c)m(k)g(b)s(efore)g(it)f(gets)i(\015ushed)d(out)j(of)f(the)g(IO) f(bu\013er.)40 b(It)30 b(is)f(imp)s(ortan)m(t)g(to)0 2795 y(a)m(v)m(oid)e(the)g(situation)e(where)h(the)h(same)g(FITS)e(blo) s(c)m(k)h(is)g(b)s(eing)f(read)h(then)g(\015ushed)f(from)h(a)h(IO)f (bu\013er)f(m)m(ultiple)0 2908 y(times.)0 3068 y(The)30 b(follo)m(wing)f(section)h(giv)m(es)h(more)f(sp)s(eci\014c)g (suggestions)g(for)g(optimizing)f(the)h(use)g(of)h(CFITSIO.)0 3481 y Ff(13.2)136 b(Optimization)46 b(Strategies)0 3747 y Fj(1.)54 b(When)34 b(dealing)f(with)h(a)h(FITS)e(primary)g(arra)m(y)i (or)g(IMA)m(GE)g(extension,)h(it)e(is)f(more)i(e\016cien)m(t)g(to)g (read)g(or)0 3860 y(write)30 b(large)g(c)m(h)m(unks)g(of)g(the)h(image) f(at)i(a)e(time)g(\(at)i(least)e(3)h(FITS)f(blo)s(c)m(ks)f(=)h(8640)i (b)m(ytes\))f(so)g(that)g(the)f(direct)0 3973 y(IO)j(mec)m(hanism)g (will)d(b)s(e)j(used)g(as)g(describ)s(ed)f(in)g(the)h(previous)f (section.)50 b(Smaller)32 b(c)m(h)m(unks)h(of)g(data)h(are)g(read)0 4086 y(or)d(written)f(via)h(the)g(IO)f(bu\013ers,)g(whic)m(h)g(is)g (somewhat)h(less)f(e\016cien)m(t)i(b)s(ecause)f(of)g(the)g(extra)h(cop) m(y)f(op)s(eration)0 4199 y(and)26 b(additional)e(b)s(o)s(okk)m(eeping) i(steps)h(that)g(are)g(required.)38 b(In)26 b(principle)d(it)j(is)g (more)g(e\016cien)m(t)h(to)h(read)e(or)h(write)0 4312 y(as)i(big)f(an)h(arra)m(y)h(of)f(image)g(pixels)e(at)j(one)f(time)f (as)i(p)s(ossible,)d(ho)m(w)m(ev)m(er,)j(if)e(the)i(arra)m(y)f(b)s (ecomes)g(so)g(large)g(that)0 4425 y(the)j(op)s(erating)f(system)g (cannot)h(store)g(it)f(all)g(in)f(RAM,)i(then)f(the)h(p)s(erformance)f (ma)m(y)h(b)s(e)f(degraded)g(b)s(ecause)0 4538 y(of)g(the)f(increased)g (sw)m(apping)f(of)h(virtual)f(memory)h(to)h(disk.)0 4698 y(2.)51 b(When)33 b(dealing)g(with)f(FITS)h(tables,)i(the)f(most)g(imp) s(ortan)m(t)f(e\016ciency)g(factor)i(in)d(the)i(soft)m(w)m(are)h (design)e(is)0 4811 y(to)k(read)f(or)g(write)f(the)h(data)h(in)e(the)h (FITS)g(\014le)f(in)g(a)h(single)f(pass)h(through)f(the)h(\014le.)57 b(An)36 b(example)g(of)g(p)s(o)s(or)0 4924 y(program)g(design)g(w)m (ould)f(b)s(e)h(to)h(read)g(a)f(large,)j(3-column)d(table)g(b)m(y)h (sequen)m(tially)e(reading)h(the)g(en)m(tire)h(\014rst)0 5036 y(column,)24 b(then)g(going)g(bac)m(k)g(to)h(read)e(the)h(2nd)g (column,)g(and)f(\014nally)f(the)i(3rd)f(column;)i(this)e(ob)m(viously) f(requires)0 5149 y(3)27 b(passes)g(through)g(the)g(\014le)f(whic)m(h)g (could)g(triple)f(the)j(execution)f(time)g(of)g(an)g(IO)f(limited)f (program.)40 b(F)-8 b(or)27 b(small)0 5262 y(tables)j(this)f(is)h(not)g (imp)s(ortan)m(t,)g(but)g(when)f(reading)g(m)m(ulti-megab)m(yte)i (sized)f(tables)g(these)h(ine\016ciencies)e(can)0 5375 y(b)s(ecome)g(signi\014can)m(t.)39 b(The)28 b(more)h(e\016cien)m(t)g (pro)s(cedure)e(in)h(this)f(case)j(is)d(to)j(read)e(or)h(write)f(only)f (as)i(man)m(y)g(ro)m(ws)0 5488 y(of)j(the)g(table)f(as)h(will)d(\014t)j (in)m(to)f(the)h(a)m(v)-5 b(ailable)31 b(in)m(ternal)f(IO)h(bu\013ers,) h(then)f(access)i(all)d(the)i(necessary)g(columns)0 5601 y(of)f(data)h(within)c(that)k(range)f(of)g(ro)m(ws.)43 b(Then)29 b(after)j(the)f(program)g(is)f(completely)g(\014nished)f (with)g(the)j(data)f(in)0 5714 y(those)i(ro)m(ws)e(it)h(can)g(mo)m(v)m (e)i(on)e(to)g(the)h(next)f(range)g(of)g(ro)m(ws)g(that)h(will)c(\014t) j(in)f(the)h(bu\013ers,)f(con)m(tin)m(uing)g(in)g(this)p eop %%Page: 145 153 145 152 bop 0 299 a Fh(13.2.)73 b(OPTIMIZA)-8 b(TION)29 b(STRA)-8 b(TEGIES)2186 b Fj(145)0 555 y(w)m(a)m(y)28 b(un)m(til)d(the)h(en)m(tire)h(\014le)f(has)g(b)s(een)g(pro)s(cessed.) 39 b(By)27 b(using)e(this)h(pro)s(cedure)f(of)i(accessing)g(all)f(the)g (columns)g(of)0 668 y(a)k(table)f(in)f(parallel)f(rather)i(than)g (sequen)m(tially)-8 b(,)29 b(eac)m(h)h(blo)s(c)m(k)f(of)h(the)f(FITS)g (\014le)f(will)e(only)j(b)s(e)f(read)i(or)f(written)0 781 y(once.)0 941 y(The)g(optimal)f(n)m(um)m(b)s(er)g(of)i(ro)m(ws)f (to)i(read)e(or)g(write)g(at)h(one)g(time)f(in)f(a)i(giv)m(en)f(table)h (dep)s(ends)d(on)j(the)f(width)f(of)0 1054 y(the)j(table)g(ro)m(w,)g (on)g(the)g(n)m(um)m(b)s(er)f(of)h(IO)g(bu\013ers)e(that)j(ha)m(v)m(e)g (b)s(een)e(allo)s(cated)h(in)f(CFITSIO,)g(and)g(also)h(on)g(the)0 1167 y(n)m(um)m(b)s(er)f(of)h(other)g(FITS)f(\014les)g(that)i(are)f(op) s(en)f(at)i(the)f(same)g(time)g(\(since)g(one)g(IO)f(bu\013er)g(is)g (alw)m(a)m(ys)i(reserv)m(ed)0 1280 y(for)i(eac)m(h)h(op)s(en)e(FITS)g (\014le\).)50 b(The)34 b(CFITSIO)e(Iterator)j(routine)e(will)e (automatically)j(use)f(the)h(optimal-sized)0 1393 y(bu\013er,)43 b(but)c(there)i(is)f(also)h(a)g(CFITSIO)e(routine)h(that)h(will)d (return)i(the)h(optimal)e(n)m(um)m(b)s(er)h(of)g(ro)m(ws)h(for)g(a)0 1506 y(giv)m(en)36 b(table:)52 b(\014ts)p 644 1506 28 4 v 32 w(get)p 796 1506 V 34 w(ro)m(wsize.)57 b(It)37 b(is)d(not)j(critical)d(to)j(use)f(exactly)g(the)h(v)-5 b(alue)35 b(of)h(nro)m(ws)f(returned)g(b)m(y)h(this)0 1619 y(routine,)30 b(as)h(long)f(as)h(one)g(do)s(es)f(not)h(exceed)g (it.)41 b(Using)30 b(a)h(v)m(ery)g(small)e(v)-5 b(alue)30 b(ho)m(w)m(ev)m(er)i(can)f(also)f(lead)h(to)g(p)s(o)s(or)0 1732 y(p)s(erformance)f(b)s(ecause)g(of)h(the)f(o)m(v)m(erhead)i(from)e (the)g(larger)g(n)m(um)m(b)s(er)f(of)i(subroutine)d(calls.)0 1892 y(The)36 b(optimal)f(n)m(um)m(b)s(er)g(of)h(ro)m(ws)g(returned)f (b)m(y)i(\014ts)p 1829 1892 V 32 w(get)p 1981 1892 V 34 w(ro)m(wsize)f(is)g(v)-5 b(alid)34 b(only)h(as)i(long)f(as)g(the)h (application)0 2005 y(program)27 b(is)f(only)g(reading)h(or)g(writing)e (data)j(in)e(the)h(sp)s(eci\014ed)e(table.)40 b(An)m(y)27 b(other)g(calls)g(to)h(access)g(data)g(in)e(the)0 2118 y(table)31 b(header)g(or)g(in)e(an)m(y)j(other)f(FITS)f(\014le)g(w)m (ould)g(cause)h(additional)e(blo)s(c)m(ks)i(of)g(data)g(to)h(b)s(e)e (loaded)h(in)m(to)g(the)0 2230 y(IO)c(bu\013ers)g(displacing)f(data)i (from)g(the)g(original)e(table,)j(and)e(should)f(b)s(e)i(a)m(v)m(oided) g(during)e(the)i(critical)f(p)s(erio)s(d)0 2343 y(while)h(the)j(table)f (is)g(b)s(eing)f(read)h(or)g(written.)0 2503 y(Occasionally)f(it)g(is)f (necessary)i(to)h(sim)m(ultaneously)c(access)k(more)f(than)f(one)h (FITS)f(table,)h(for)g(example)f(when)0 2616 y(transferring)41 b(v)-5 b(alues)42 b(from)g(an)h(input)d(table)j(to)g(an)g(output)f (table.)78 b(In)42 b(cases)h(lik)m(e)f(this,)j(one)e(should)e(call)0 2729 y(\014ts)p 127 2729 V 32 w(get)p 279 2729 V 34 w(ro)m(wsize)24 b(to)g(get)h(the)f(optimal)e(n)m(um)m(b)s(er)g(of)i(ro)m(ws)g(for)f (eac)m(h)i(table)e(separately)-8 b(,)26 b(than)d(reduce)h(the)f(n)m(um) m(b)s(er)0 2842 y(of)31 b(ro)m(ws)h(prop)s(ortionally)-8 b(.)41 b(F)-8 b(or)32 b(example,)f(if)f(the)i(optimal)e(n)m(um)m(b)s (er)g(of)h(ro)m(ws)g(in)f(the)i(input)d(table)i(is)g(3600)i(and)0 2955 y(is)f(1400)i(in)e(the)h(output)f(table,)h(then)g(these)g(v)-5 b(alues)32 b(should)f(b)s(e)h(cut)h(in)e(half)h(to)h(1800)i(and)d(700,) j(resp)s(ectiv)m(ely)-8 b(,)0 3068 y(if)29 b(b)s(oth)h(tables)g(are)h (going)f(to)h(b)s(e)f(accessed)i(at)f(the)f(same)h(time.)0 3228 y(3.)39 b(Use)25 b(the)g(CFITSIO)e(Iterator)j(routine.)38 b(This)23 b(routine)h(pro)m(vides)f(a)j(more)e(`ob)5 b(ject)26 b(orien)m(ted')f(w)m(a)m(y)h(of)f(reading)0 3341 y(and)34 b(writing)e(FITS)i(\014les)f(whic)m(h)h(automatically)g (uses)g(the)g(most)h(appropriate)f(data)h(bu\013er)e(size)h(to)i(ac)m (hiev)m(e)0 3454 y(the)31 b(maxim)m(um)e(I/O)h(throughput.)0 3614 y(4.)39 b(Use)24 b(binary)e(table)h(extensions)g(rather)g(than)h (ASCI)s(I)e(table)h(extensions)g(for)g(b)s(etter)h(e\016ciency)g(when)e (dealing)0 3727 y(with)36 b(tabular)h(data.)62 b(The)37 b(I/O)g(to)h(ASCI)s(I)e(tables)h(is)g(slo)m(w)m(er)g(b)s(ecause)h(of)f (the)h(o)m(v)m(erhead)h(in)d(formatting)h(or)0 3840 y(parsing)31 b(the)h(ASCI)s(I)f(data)i(\014elds)e(and)h(b)s(ecause)g(ASCI)s(I)f (tables)h(are)h(ab)s(out)f(t)m(wice)h(as)g(large)f(as)h(binary)d (tables)0 3953 y(with)f(the)i(same)f(information)f(con)m(ten)m(t.)0 4113 y(5.)64 b(Design)38 b(soft)m(w)m(are)h(so)g(that)f(it)g(reads)g (the)g(FITS)f(header)h(k)m(eyw)m(ords)g(in)f(the)h(same)h(order)e(in)g (whic)m(h)g(they)0 4226 y(o)s(ccur)28 b(in)g(the)h(\014le.)39 b(When)28 b(reading)g(k)m(eyw)m(ords,)i(CFITSIO)d(searc)m(hes)i(forw)m (ard)g(starting)f(from)g(the)h(p)s(osition)e(of)0 4339 y(the)i(last)h(k)m(eyw)m(ord)f(that)h(w)m(as)g(read.)40 b(If)29 b(it)f(reac)m(hes)j(the)e(end)g(of)g(the)h(header)f(without)f (\014nding)f(the)i(k)m(eyw)m(ord,)h(it)0 4452 y(then)j(go)s(es)h(bac)m (k)g(to)h(the)e(start)h(of)g(the)g(header)f(and)g(con)m(tin)m(ues)g (the)h(searc)m(h)g(do)m(wn)f(to)h(the)g(p)s(osition)d(where)i(it)0 4565 y(started.)41 b(In)30 b(practice,)h(as)f(long)g(as)h(the)f(en)m (tire)h(FITS)e(header)h(can)h(\014t)f(at)h(one)g(time)f(in)f(the)h(a)m (v)-5 b(ailable)30 b(in)m(ternal)0 4678 y(IO)36 b(bu\013ers,)h(then)f (the)g(header)g(k)m(eyw)m(ord)h(access)g(will)d(b)s(e)i(v)m(ery)g(fast) h(and)f(it)f(mak)m(es)i(little)e(di\013erence)h(whic)m(h)0 4791 y(order)30 b(they)g(are)h(accessed.)0 4951 y(6.)40 b(Av)m(oid)28 b(the)f(use)h(of)f(scaling)g(\(b)m(y)h(using)e(the)i (BSCALE)e(and)h(BZER)m(O)h(or)f(TSCAL)g(and)g(TZER)m(O)f(k)m(eyw)m (ords\))0 5064 y(in)34 b(FITS)g(\014les)f(since)i(the)g(scaling)f(op)s (erations)g(add)g(to)i(the)f(pro)s(cessing)e(time)i(needed)f(to)i(read) f(or)g(write)f(the)0 5176 y(data.)39 b(In)24 b(some)h(cases)h(it)e(ma)m (y)h(b)s(e)f(more)g(e\016cien)m(t)h(to)h(temp)s(orarily)c(turn)i(o\013) h(the)f(scaling)g(\(using)f(\014ts)p 3490 5176 V 33 w(set)p 3634 5176 V 33 w(bscale)0 5289 y(or)30 b(\014ts)p 238 5289 V 33 w(set)p 382 5289 V 33 w(tscale\))i(and)d(then)h(read)h(or)f (write)g(the)g(ra)m(w)h(unscaled)e(v)-5 b(alues)30 b(in)f(the)h(FITS)g (\014le.)0 5450 y(7.)77 b(Av)m(oid)42 b(using)f(the)i(`implicit)c(data) 44 b(t)m(yp)s(e)e(con)m(v)m(ersion')h(capabilit)m(y)e(in)g(CFITSIO.)g (F)-8 b(or)44 b(instance,)h(when)0 5562 y(reading)27 b(a)h(FITS)f(image)h(with)e(BITPIX)i(=)f(-32)i(\(32-bit)f(\015oating)g (p)s(oin)m(t)f(pixels\),)g(read)g(the)h(data)g(in)m(to)g(a)g(single)0 5675 y(precision)38 b(\015oating)i(p)s(oin)m(t)f(data)i(arra)m(y)f(in)f (the)h(program.)69 b(F)-8 b(orcing)40 b(CFITSIO)f(to)i(con)m(v)m(ert)g (the)f(data)h(to)g(a)p eop %%Page: 146 154 146 153 bop 0 299 a Fj(146)1876 b Fh(CHAPTER)30 b(13.)112 b(OPTIMIZING)29 b(PR)m(OGRAMS)0 555 y Fj(di\013eren)m(t)h(data)h(t)m (yp)s(e)f(can)h(slo)m(w)f(the)h(program.)0 715 y(8.)57 b(Where)36 b(feasible,)g(design)f(FITS)g(binary)f(tables)h(using)f(v)m (ector)k(column)c(elemen)m(ts)i(so)g(that)g(the)g(data)h(are)0 828 y(written)29 b(as)h(a)g(con)m(tiguous)g(set)g(of)g(b)m(ytes,)g (rather)g(than)f(as)h(single)e(elemen)m(ts)i(in)f(m)m(ultiple)e(ro)m (ws.)41 b(F)-8 b(or)30 b(example,)0 941 y(it)35 b(is)g(faster)h(to)g (access)h(the)f(data)h(in)d(a)i(table)g(that)g(con)m(tains)g(a)g (single)e(ro)m(w)i(and)f(2)h(columns)e(with)h(TF)m(ORM)0 1054 y(k)m(eyw)m(ords)e(equal)g(to)h('10000E')h(and)e('10000J',)j(than) d(it)f(is)g(to)i(access)g(the)g(same)f(amoun)m(t)h(of)f(data)h(in)e(a)h (table)0 1167 y(with)39 b(10000)k(ro)m(ws)d(whic)m(h)g(has)g(columns)f (with)g(the)i(TF)m(ORM)g(k)m(eyw)m(ords)g(equal)f(to)h('1E')h(and)e ('1J'.)h(In)f(the)0 1280 y(former)27 b(case)i(the)f(10000)i(\015oating) e(p)s(oin)m(t)f(v)-5 b(alues)27 b(in)g(the)h(\014rst)f(column)g(are)h (all)f(written)g(in)f(a)i(con)m(tiguous)g(blo)s(c)m(k)0 1393 y(of)e(the)f(\014le)g(whic)m(h)f(can)i(b)s(e)f(read)g(or)g (written)g(quic)m(kly)-8 b(,)26 b(whereas)f(in)f(the)i(second)f(case)i (eac)m(h)g(\015oating)e(p)s(oin)m(t)f(v)-5 b(alue)0 1506 y(in)33 b(the)h(\014rst)f(column)f(is)h(in)m(terlea)m(v)m(ed)i(with)d (the)i(in)m(teger)h(v)-5 b(alue)33 b(in)g(the)h(second)g(column)e(of)i (the)g(same)h(ro)m(w)f(so)0 1619 y(CFITSIO)29 b(has)h(to)h(explicitly)d (mo)m(v)m(e)k(to)f(the)g(p)s(osition)d(of)j(eac)m(h)g(elemen)m(t)g(to)g (b)s(e)f(read)g(or)g(written.)0 1779 y(9.)52 b(Av)m(oid)34 b(the)h(use)e(of)i(v)-5 b(ariable)32 b(length)i(v)m(ector)i(columns)c (in)h(binary)g(tables,)i(since)e(an)m(y)i(reading)e(or)h(writing)0 1892 y(of)f(these)g(data)g(requires)e(that)i(CFITSIO)f(\014rst)f(lo)s (ok)i(up)e(or)i(compute)g(the)f(starting)h(address)f(of)g(eac)m(h)i(ro) m(w)f(of)0 2005 y(data)e(in)e(the)i(heap.)0 2165 y(10.)73 b(When)40 b(cop)m(ying)h(data)h(from)e(one)h(FITS)f(table)h(to)g (another,)j(it)d(is)e(faster)j(to)f(transfer)g(the)f(ra)m(w)h(b)m(ytes) 0 2278 y(instead)27 b(of)i(reading)e(then)h(writing)e(eac)m(h)j(column) e(of)h(the)g(table.)40 b(The)28 b(CFITSIO)e(routines)h(\014ts)p 3349 2278 28 4 v 33 w(read)p 3554 2278 V 32 w(tblb)m(ytes)0 2391 y(and)36 b(\014ts)p 310 2391 V 32 w(write)p 545 2391 V 32 w(tblb)m(ytes)h(will)d(p)s(erform)h(lo)m(w-lev)m(el)h(reads)h (or)f(writes)g(of)h(an)m(y)g(con)m(tiguous)f(range)h(of)g(b)m(ytes)g (in)0 2503 y(a)d(table)f(extension.)50 b(These)33 b(routines)g(can)g(b) s(e)g(used)g(to)h(read)f(or)h(write)f(a)g(whole)g(ro)m(w)h(\(or)g(m)m (ultiple)d(ro)m(ws)i(for)0 2616 y(ev)m(en)e(greater)h(e\016ciency\))g (of)f(a)g(table)g(with)e(a)i(single)f(function)f(call.)41 b(These)31 b(routines)f(are)h(fast)g(b)s(ecause)g(they)0 2729 y(b)m(ypass)36 b(all)f(the)i(usual)e(data)i(scaling,)g(error)f(c)m (hec)m(king)h(and)f(mac)m(hine)g(dep)s(enden)m(t)f(data)i(con)m(v)m (ersion)g(that)g(is)0 2842 y(normally)e(done)i(b)m(y)f(CFITSIO,)g(and)g (they)h(allo)m(w)f(the)i(program)e(to)i(write)e(the)h(data)g(to)h(the)f (output)f(\014le)g(in)0 2955 y(exactly)29 b(the)f(same)h(b)m(yte)g (order.)40 b(F)-8 b(or)29 b(these)f(same)h(reasons,)g(these)g(routines) e(can)h(corrupt)g(the)g(FITS)g(data)h(\014le)0 3068 y(if)35 b(used)f(incorrectly)h(b)s(ecause)h(no)f(v)-5 b(alidation)34 b(or)i(mac)m(hine)f(dep)s(enden)m(t)f(con)m(v)m(ersion)i(is)f(p)s (erformed)f(b)m(y)h(these)0 3181 y(routines.)54 b(These)35 b(routines)f(are)i(only)e(recommended)h(for)g(optimizing)e(critical)h (pieces)h(of)h(co)s(de)f(and)g(should)0 3294 y(only)d(b)s(e)h(used)g(b) m(y)g(programmers)g(who)g(thoroughly)f(understand)f(the)j(in)m(ternal)e (format)i(of)f(the)h(FITS)e(tables)0 3407 y(they)f(are)f(reading)g(or)g (writing.)0 3567 y(11.)41 b(Another)30 b(strategy)g(for)g(impro)m(ving) d(the)j(sp)s(eed)e(of)i(writing)e(a)h(FITS)g(table,)h(similar)d(to)j (the)f(previous)f(one,)0 3680 y(is)j(to)h(directly)f(construct)h(the)f (en)m(tire)h(b)m(yte)g(stream)g(for)g(a)g(whole)f(table)g(ro)m(w)h (\(or)g(m)m(ultiple)e(ro)m(ws\))i(within)d(the)0 3793 y(application)f(program)h(and)g(then)h(write)f(it)g(to)h(the)g(FITS)f (\014le)g(with)f(\014ts)p 2520 3793 V 32 w(write)p 2755 3793 V 32 w(tblb)m(ytes.)40 b(This)28 b(a)m(v)m(oids)i(all)f(the)0 3906 y(o)m(v)m(erhead)h(normally)e(presen)m(t)h(in)f(the)i (column-orien)m(ted)e(CFITSIO)g(write)g(routines.)39 b(This)28 b(tec)m(hnique)h(should)0 4019 y(only)34 b(b)s(e)f(used)h (for)g(critical)f(applications)g(b)s(ecause)h(it)g(mak)m(es)i(the)e(co) s(de)h(more)f(di\016cult)f(to)i(understand)e(and)0 4131 y(main)m(tain,)j(and)f(it)g(mak)m(es)h(the)g(co)s(de)f(more)h(system)g (dep)s(enden)m(t)e(\(e.g.,)39 b(do)c(the)h(b)m(ytes)g(need)f(to)h(b)s (e)f(sw)m(app)s(ed)0 4244 y(b)s(efore)30 b(writing)e(to)j(the)g(FITS)f (\014le?\).)0 4405 y(12.)53 b(Finally)-8 b(,)34 b(external)g(factors)i (suc)m(h)e(as)g(the)h(t)m(yp)s(e)f(of)h(magnetic)f(disk)f(con)m (troller)h(\(SCSI)f(or)i(IDE\),)g(the)f(size)0 4517 y(of)h(the)g(disk)f (cac)m(he,)k(the)d(a)m(v)m(erage)i(seek)f(sp)s(eed)e(of)h(the)g(disk,)g (the)g(amoun)m(t)h(of)f(disk)e(fragmen)m(tation,)k(and)e(the)0 4630 y(amoun)m(t)29 b(of)g(RAM)f(a)m(v)-5 b(ailable)28 b(on)h(the)f(system)h(can)g(all)e(ha)m(v)m(e)j(a)f(signi\014can)m(t)e (impact)i(on)f(o)m(v)m(erall)h(I/O)f(e\016ciency)-8 b(.)0 4743 y(F)g(or)36 b(critical)e(applications,)g(a)i(system)f (administrator)e(should)g(review)h(the)i(prop)s(osed)d(system)j(hardw)m (are)e(to)0 4856 y(iden)m(tify)29 b(an)m(y)i(p)s(oten)m(tial)e(I/O)i(b) s(ottlenec)m(ks.)p eop %%Page: 147 155 147 154 bop 0 1225 a Fg(App)5 b(endix)65 b(A)0 1687 y Fm(Index)77 b(of)h(Routines)50 2154 y Fj(\014ts)p 177 2154 28 4 v 32 w(add)p 356 2154 V 32 w(group)p 616 2154 V 33 w(mem)m(b)s(er)144 b(78)50 2267 y(\014ts)p 177 2267 V 32 w(ascii)p 382 2267 V 32 w(tform)478 b(59)50 2380 y(\014ts)p 177 2380 V 32 w(binary)p 466 2380 V 31 w(tform)395 b(59)50 2493 y(\014ts)p 177 2493 V 32 w(calculator)514 b(52)50 2606 y(\014ts)p 177 2606 V 32 w(calculator)p 598 2606 V 33 w(rng)349 b(53)50 2719 y(\014ts)p 177 2719 V 32 w(calc)p 360 2719 V 34 w(ro)m(ws)538 b(52)50 2832 y(\014ts)p 177 2832 V 32 w(c)m(hange)p 478 2832 V 34 w(group)372 b(76)50 2945 y(\014ts)p 177 2945 V 32 w(clear)p 396 2945 V 33 w(errmark)366 b(30)50 3057 y(\014ts)p 177 3057 V 32 w(clear)p 396 3057 V 33 w(errmsg)414 b(30)50 3170 y(\014ts)p 177 3170 V 32 w(close)p 396 3170 V 33 w(\014le)566 b(33)50 3283 y(\014ts)p 177 3283 V 32 w(compact)p 541 3283 V 34 w(group)309 b(77)50 3396 y(\014ts)p 177 3396 V 32 w(compare)p 542 3396 V 34 w(str)429 b(56)50 3509 y(\014ts)p 177 3509 V 32 w(compress)p 569 3509 V 33 w(heap)278 b(100)50 3622 y(\014ts)p 177 3622 V 32 w(cop)m(y)p 390 3622 V 34 w(col)577 b(49)50 3735 y(\014ts)p 177 3735 V 32 w(cop)m(y)p 390 3735 V 34 w(data)512 b(86)50 3848 y(\014ts)p 177 3848 V 32 w(cop)m(y)p 390 3848 V 34 w(\014le)571 b(34)50 3961 y(\014ts)p 177 3961 V 32 w(cop)m(y)p 390 3961 V 34 w(group)460 b(77)50 4074 y(\014ts)p 177 4074 V 32 w(cop)m(y)p 390 4074 V 34 w(hdu)535 b(34)50 4187 y(\014ts)p 177 4187 V 32 w(cop)m(y)p 390 4187 V 34 w(header)425 b(34)50 4299 y(\014ts)p 177 4299 V 32 w(cop)m(y)p 390 4299 V 34 w(k)m(ey)555 b(89)50 4412 y(\014ts)p 177 4412 V 32 w(cop)m(y)p 390 4412 V 34 w(mem)m(b)s(er)369 b(79)50 4525 y(\014ts)p 177 4525 V 32 w(create)p 445 4525 V 35 w(disk\014le)354 b(32)50 4638 y(\014ts)p 177 4638 V 32 w(create)p 445 4638 V 35 w(\014le)515 b(32)50 4751 y(\014ts)p 177 4751 V 32 w(create)p 445 4751 V 35 w(group)404 b(76)50 4864 y(\014ts)p 177 4864 V 32 w(create)p 445 4864 V 35 w(hdu)479 b(84)50 4977 y(\014ts)p 177 4977 V 32 w(create)p 445 4977 V 35 w(img)485 b(40)50 5090 y(\014ts)p 177 5090 V 32 w(create)p 445 5090 V 35 w(mem\014le)323 b(82)50 5203 y(\014ts)p 177 5203 V 32 w(create)p 445 5203 V 35 w(tbl)520 b(46)50 5316 y(\014ts)p 177 5316 V 32 w(create)p 445 5316 V 35 w(template)284 b(82)50 5429 y(\014ts)p 177 5429 V 32 w(date2str)580 b(55)50 5541 y(\014ts)p 177 5541 V 32 w(deco)s(de)p 479 5541 V 33 w(c)m(hksum)301 b(54)50 5654 y(\014ts)p 177 5654 V 32 w(deco)s(de)p 479 5654 V 33 w(tdim)412 b(48)1325 2154 y(\014ts)p 1452 2154 V 33 w(delete)p 1717 2154 V 33 w(col)565 b(49)1325 2267 y(\014ts)p 1452 2267 V 33 w(delete)p 1717 2267 V 33 w(\014le)559 b(33)1325 2380 y(\014ts)p 1452 2380 V 33 w(delete)p 1717 2380 V 33 w(hdu)523 b(35)1325 2493 y(\014ts)p 1452 2493 V 33 w(delete)p 1717 2493 V 33 w(k)m(ey)543 b(39)1325 2606 y(\014ts)p 1452 2606 V 33 w(delete)p 1717 2606 V 33 w(record)428 b(39)1325 2719 y(\014ts)p 1452 2719 V 33 w(delete)p 1717 2719 V 33 w(ro)m(wlist)409 b(48)1325 2832 y(\014ts)p 1452 2832 V 33 w(delete)p 1717 2832 V 33 w(ro)m(wrange)315 b(48)1325 2945 y(\014ts)p 1452 2945 V 33 w(delete)p 1717 2945 V 33 w(ro)m(ws)496 b(48)1325 3057 y(\014ts)p 1452 3057 V 33 w(enco)s(de)p 1755 3057 V 33 w(c)m(hksum)339 b(54)1325 3170 y(\014ts)p 1452 3170 V 33 w(\014le)p 1602 3170 V 32 w(exists)571 b(83)1325 3283 y(\014ts)p 1452 3283 V 33 w(\014le)p 1602 3283 V 32 w(mo)s(de)577 b(33)1325 3396 y(\014ts)p 1452 3396 V 33 w(\014le)p 1602 3396 V 32 w(name)j(33)1325 3509 y(\014ts)p 1452 3509 V 33 w(\014nd)p 1638 3509 V 31 w(\014rst)p 1827 3509 V 32 w(ro)m(w)423 b(52)1325 3622 y(\014ts)p 1452 3622 V 33 w(\014nd)p 1638 3622 V 31 w(nextk)m(ey)450 b(36)1325 3735 y(\014ts)p 1452 3735 V 33 w(\014nd)p 1638 3735 V 31 w(ro)m(ws)577 b(52)1325 3848 y(\014ts)p 1452 3848 V 33 w(\015ush)p 1674 3848 V 31 w(bu\013er)490 b(84)1325 3961 y(\014ts)p 1452 3961 V 33 w(\015ush)p 1674 3961 V 31 w(\014le)604 b(84)1325 4074 y(\014ts)p 1452 4074 V 33 w(get)p 1605 4074 V 34 w(acolparms)387 b(99)1325 4187 y(\014ts)p 1452 4187 V 33 w(get)p 1605 4187 V 34 w(b)s(colparms)378 b(99)1325 4299 y(\014ts)p 1452 4299 V 33 w(get)p 1605 4299 V 34 w(c)m(hksum)488 b(54)1325 4412 y(\014ts)p 1452 4412 V 33 w(get)p 1605 4412 V 34 w(col)p 1750 4412 V 32 w(displa)m(y)p 2062 4412 V 31 w(width)104 b(48)1325 4525 y(\014ts)p 1452 4525 V 33 w(get)p 1605 4525 V 34 w(colname)464 b(46)1325 4638 y(\014ts)p 1452 4638 V 33 w(get)p 1605 4638 V 34 w(coln)m(um)501 b(46)1325 4751 y(\014ts)p 1452 4751 V 33 w(get)p 1605 4751 V 34 w(colt)m(yp)s(e)h(47)1325 4864 y(\014ts)p 1452 4864 V 33 w(get)p 1605 4864 V 34 w(compression)p 2121 4864 V 31 w(t)m(yp)s(e)100 b(44)1325 4977 y(\014ts)p 1452 4977 V 33 w(get)p 1605 4977 V 34 w(eqcolt)m(yp)s(e)414 b(47)1325 5090 y(\014ts)p 1452 5090 V 33 w(get)p 1605 5090 V 34 w(errstatus)437 b(29)1325 5203 y(\014ts)p 1452 5203 V 33 w(get)p 1605 5203 V 34 w(hdrp)s(os)514 b(86)1325 5316 y(\014ts)p 1452 5316 V 33 w(get)p 1605 5316 V 34 w(hdrspace)437 b(35)1325 5429 y(\014ts)p 1452 5429 V 33 w(get)p 1605 5429 V 34 w(hdu)p 1792 5429 V 31 w(n)m(um)428 b(34)1325 5541 y(\014ts)p 1452 5541 V 33 w(get)p 1605 5541 V 34 w(hdu)p 1792 5541 V 31 w(t)m(yp)s(e)h(34)1325 5654 y(\014ts)p 1452 5654 V 33 w(get)p 1605 5654 V 34 w(hduaddr)451 b(84)2639 2154 y(\014ts)p 2766 2154 V 33 w(get)p 2919 2154 V 34 w(hduo\013)560 b(84)2639 2267 y(\014ts)p 2766 2267 V 33 w(get)p 2919 2267 V 34 w(img)p 3100 2267 V 32 w(dim)479 b(40)2639 2380 y(\014ts)p 2766 2380 V 33 w(get)p 2919 2380 V 34 w(img)p 3100 2380 V 32 w(equivt)m(yp)s(e)245 b(40)2639 2493 y(\014ts)p 2766 2493 V 33 w(get)p 2919 2493 V 34 w(img)p 3100 2493 V 32 w(param)379 b(40)2639 2606 y(\014ts)p 2766 2606 V 33 w(get)p 2919 2606 V 34 w(img)p 3100 2606 V 32 w(size)490 b(40)2639 2719 y(\014ts)p 2766 2719 V 33 w(get)p 2919 2719 V 34 w(img)p 3100 2719 V 32 w(t)m(yp)s(e)458 b(40)2639 2832 y(\014ts)p 2766 2832 V 33 w(get)p 2919 2832 V 34 w(k)m(eyclass)495 b(58)2639 2945 y(\014ts)p 2766 2945 V 33 w(get)p 2919 2945 V 34 w(k)m(eyname)466 b(57)2639 3057 y(\014ts)p 2766 3057 V 33 w(get)p 2919 3057 V 34 w(k)m(eyt)m(yp)s(e)504 b(58)2639 3170 y(\014ts)p 2766 3170 V 33 w(get)p 2919 3170 V 34 w(noise)p 3151 3170 V 32 w(bits)433 b(44)2639 3283 y(\014ts)p 2766 3283 V 33 w(get)p 2919 3283 V 34 w(n)m(um)p 3128 3283 V 32 w(cols)457 b(46)2639 3396 y(\014ts)p 2766 3396 V 33 w(get)p 2919 3396 V 34 w(n)m(um)p 3128 3396 V 32 w(groups)340 b(79)2639 3509 y(\014ts)p 2766 3509 V 33 w(get)p 2919 3509 V 34 w(n)m(um)p 3128 3509 V 32 w(hdus)415 b(33)2639 3622 y(\014ts)p 2766 3622 V 33 w(get)p 2919 3622 V 34 w(n)m(um)p 3128 3622 V 32 w(mem)m(b)s(ers)249 b(78)2639 3735 y(\014ts)p 2766 3735 V 33 w(get)p 2919 3735 V 34 w(n)m(um)p 3128 3735 V 32 w(ro)m(ws)424 b(46)2639 3848 y(\014ts)p 2766 3848 V 33 w(get)p 2919 3848 V 34 w(ro)m(wsize)525 b(99)2639 3961 y(\014ts)p 2766 3961 V 33 w(get)p 2919 3961 V 34 w(system)p 3224 3961 V 33 w(time)330 b(55)2639 4074 y(\014ts)p 2766 4074 V 33 w(get)p 2919 4074 V 34 w(tile)p 3080 4074 V 32 w(dim)499 b(44)2639 4187 y(\014ts)p 2766 4187 V 33 w(get)p 2919 4187 V 34 w(tb)s(col)611 b(59)2639 4299 y(\014ts)p 2766 4299 V 33 w(get)p 2919 4299 V 34 w(v)m(ersion)532 b(56)2639 4412 y(\014ts)p 2766 4412 V 33 w(hdr2str)d(37,)31 b(72)2639 4525 y(\014ts)p 2766 4525 V 33 w(insert)p 3023 4525 V 31 w(atbl)553 b(85)2639 4638 y(\014ts)p 2766 4638 V 33 w(insert)p 3023 4638 V 31 w(btbl)547 b(85)2639 4751 y(\014ts)p 2766 4751 V 33 w(insert)p 3023 4751 V 31 w(col)599 b(49)2639 4864 y(\014ts)p 2766 4864 V 33 w(insert)p 3023 4864 V 31 w(cols)563 b(49)2639 4977 y(\014ts)p 2766 4977 V 33 w(insert)p 3023 4977 V 31 w(group)482 b(76)2639 5090 y(\014ts)p 2766 5090 V 33 w(insert)p 3023 5090 V 31 w(img)563 b(85)2639 5203 y(\014ts)p 2766 5203 V 33 w(insert)p 3023 5203 V 31 w(k)m(ey)p 3187 5203 V 34 w(n)m(ull)392 b(91)2639 5316 y(\014ts)p 2766 5316 V 33 w(insert)p 3023 5316 V 31 w(k)m(ey)p 3187 5316 V 34 w(TYP)347 b(90)2639 5429 y(\014ts)p 2766 5429 V 33 w(insert)p 3023 5429 V 31 w(record)462 b(90)2639 5541 y(\014ts)p 2766 5541 V 33 w(insert)p 3023 5541 V 31 w(ro)m(ws)530 b(48)2639 5654 y(\014ts)p 2766 5654 V 33 w(iterate)p 3056 5654 V 33 w(data)499 b(69)1882 5942 y(147)p eop %%Page: 148 156 148 155 bop 0 299 a Fj(148)2084 b Fh(APPENDIX)31 b(A.)61 b(INDEX)31 b(OF)f(R)m(OUTINES)50 599 y Fj(\014ts)p 177 599 28 4 v 32 w(mak)m(e)p 415 599 V 34 w(k)m(eyn)421 b(57)50 712 y(\014ts)p 177 712 V 32 w(mak)m(e)p 415 712 V 34 w(nk)m(ey)g(58)50 825 y(\014ts)p 177 825 V 32 w(merge)p 446 825 V 34 w(groups)310 b(77)50 938 y(\014ts)p 177 938 V 32 w(mo)s(dify)p 486 938 V 31 w(card)365 b(92)50 1051 y(\014ts)p 177 1051 V 32 w(mo)s(dify)p 486 1051 V 31 w(commen)m(t)177 b(38)50 1164 y(\014ts)p 177 1164 V 32 w(mo)s(dify)p 486 1164 V 31 w(k)m(ey)p 650 1164 V 34 w(n)m(ull)219 b(93)50 1277 y(\014ts)p 177 1277 V 32 w(mo)s(dify)p 486 1277 V 31 w(k)m(ey)p 650 1277 V 34 w(TYP)174 b(93)50 1390 y(\014ts)p 177 1390 V 32 w(mo)s(dify)p 486 1390 V 31 w(name)325 b(39)50 1503 y(\014ts)p 177 1503 V 32 w(mo)s(dify)p 486 1503 V 31 w(record)289 b(92)50 1616 y(\014ts)p 177 1616 V 32 w(mo)s(dify)p 486 1616 V 31 w(v)m(ector)p 758 1616 V 35 w(len)144 b(49)50 1728 y(\014ts)p 177 1728 V 32 w(mo)m(v)-5 b(abs)p 502 1728 V 33 w(hdu)366 b(33)50 1841 y(\014ts)p 177 1841 V 32 w(mo)m(vnam)p 547 1841 V 33 w(hdu)321 b(33)50 1954 y(\014ts)p 177 1954 V 32 w(mo)m(vrel)p 477 1954 V 33 w(hdu)391 b(33)50 2067 y(\014ts)p 177 2067 V 32 w(n)m(ull)p 360 2067 V 31 w(c)m(hec)m(k)450 b(57)50 2180 y(\014ts)p 177 2180 V 32 w(op)s(en)p 399 2180 V 32 w(data)d(30)50 2293 y(\014ts)p 177 2293 V 32 w(op)s(en)p 399 2293 V 32 w(disk\014le)345 b(30)50 2406 y(\014ts)p 177 2406 V 32 w(op)s(en)p 399 2406 V 32 w(\014le)506 b(30)50 2519 y(\014ts)p 177 2519 V 32 w(op)s(en)p 399 2519 V 32 w(image)391 b(30)50 2632 y(\014ts)p 177 2632 V 32 w(op)s(en)p 399 2632 V 32 w(table)426 b(30)50 2745 y(\014ts)p 177 2745 V 32 w(op)s(en)p 399 2745 V 32 w(group)395 b(78)50 2858 y(\014ts)p 177 2858 V 32 w(op)s(en)p 399 2858 V 32 w(mem)m(b)s(er)304 b(79)50 2970 y(\014ts)p 177 2970 V 32 w(op)s(en)p 399 2970 V 32 w(mem\014le)314 b(81)50 3083 y(\014ts)p 177 3083 V 32 w(parse)p 417 3083 V 33 w(extn)m(um)306 b(83)50 3196 y(\014ts)p 177 3196 V 32 w(parse)p 417 3196 V 33 w(input)p 664 3196 V 31 w(url)246 b(82)50 3309 y(\014ts)p 177 3309 V 32 w(parse)p 417 3309 V 33 w(range)387 b(61)50 3422 y(\014ts)p 177 3422 V 32 w(parse)p 417 3422 V 33 w(ro)s(otname)228 b(83)50 3535 y(\014ts)p 177 3535 V 32 w(parse)p 417 3535 V 33 w(template)256 b(59)50 3648 y(\014ts)p 177 3648 V 32 w(parse)p 417 3648 V 33 w(v)-5 b(alue)399 b(57)50 3761 y(\014ts)p 177 3761 V 32 w(pix)p 334 3761 V 32 w(to)p 446 3761 V 33 w(w)m(orld)354 b(73)50 3874 y(\014ts)p 177 3874 V 32 w(read)p 381 3874 V 33 w(2d)p 510 3874 V 33 w(TYP)315 b(98)50 3987 y(\014ts)p 177 3987 V 32 w(read)p 381 3987 V 33 w(3d)p 510 3987 V 33 w(TYP)g(98)50 4100 y(\014ts)p 177 4100 V 32 w(read)p 381 4100 V 33 w(atblhdr)345 b(87)50 4212 y(\014ts)p 177 4212 V 32 w(read)p 381 4212 V 33 w(btblhdr)339 b(87)50 4325 y(\014ts)p 177 4325 V 32 w(read)p 381 4325 V 33 w(card)468 b(36)50 4438 y(\014ts)p 177 4438 V 32 w(read)p 381 4438 V 33 w(col)529 b(51)50 4551 y(\014ts)p 177 4551 V 32 w(read)p 381 4551 V 33 w(col)p 525 4551 V 33 w(bit)p 670 4551 V 338 w(104)50 4664 y(\014ts)p 177 4664 V 32 w(read)p 381 4664 V 33 w(col)p 525 4664 V 33 w(TYP)254 b(102)50 4777 y(\014ts)p 177 4777 V 32 w(read)p 381 4777 V 33 w(coln)m(ull)378 b(51)50 4890 y(\014ts)p 177 4890 V 32 w(read)p 381 4890 V 33 w(coln)m(ull)p 676 4890 V 31 w(TYP)105 b(103)50 5003 y(\014ts)p 177 5003 V 32 w(read)p 381 5003 V 33 w(descript)279 b(104)50 5116 y(\014ts)p 177 5116 V 32 w(read)p 381 5116 V 33 w(descripts)243 b(104)50 5229 y(\014ts)p 177 5229 V 32 w(read)p 381 5229 V 33 w(errmsg)371 b(30)50 5342 y(\014ts)p 177 5342 V 32 w(read)p 381 5342 V 33 w(grppar)p 678 5342 V 32 w(TYP)148 b(98)50 5454 y(\014ts)p 177 5454 V 32 w(read)p 381 5454 V 33 w(img)493 b(97)50 5567 y(\014ts)p 177 5567 V 32 w(read)p 381 5567 V 33 w(img)p 561 5567 V 32 w(co)s(ord)241 b(72)50 5680 y(\014ts)p 177 5680 V 32 w(read)p 381 5680 V 33 w(img)p 561 5680 V 32 w(TYP)265 b(97)50 5793 y(\014ts)p 177 5793 V 32 w(read)p 381 5793 V 33 w(imghdr)355 b(87)1260 543 y(\014ts)p 1387 543 V 32 w(read)p 1591 543 V 33 w(imgn)m(ull)596 b(97)1260 656 y(\014ts)p 1387 656 V 32 w(read)p 1591 656 V 33 w(imgn)m(ull)p 1922 656 V 30 w(TYP)370 b(97)1260 769 y(\014ts)p 1387 769 V 32 w(read)p 1591 769 V 33 w(k)m(ey)761 b(36)1260 882 y(\014ts)p 1387 882 V 32 w(read)p 1591 882 V 33 w(k)m(ey)p 1757 882 V 33 w(longstr)454 b(91)1260 995 y(\014ts)p 1387 995 V 32 w(read)p 1591 995 V 33 w(k)m(ey)p 1757 995 V 33 w(triple)514 b(92)1260 1107 y(\014ts)p 1387 1107 V 32 w(read)p 1591 1107 V 33 w(k)m(ey)p 1757 1107 V 33 w(unit)565 b(37)1260 1220 y(\014ts)p 1387 1220 V 32 w(read)p 1591 1220 V 33 w(k)m(ey)p 1757 1220 V 33 w(TYP)532 b(91)1260 1333 y(\014ts)p 1387 1333 V 32 w(read)p 1591 1333 V 33 w(k)m(eyn)710 b(36)1260 1446 y(\014ts)p 1387 1446 V 32 w(read)p 1591 1446 V 33 w(k)m(eys)p 1793 1446 V 33 w(TYP)496 b(92)1260 1559 y(\014ts)p 1387 1559 V 32 w(read)p 1591 1559 V 33 w(k)m(eyw)m(ord)566 b(36)1260 1672 y(\014ts)p 1387 1672 V 32 w(read)p 1591 1672 V 33 w(pix)769 b(42)1260 1785 y(\014ts)p 1387 1785 V 32 w(read)p 1591 1785 V 33 w(pixn)m(ull)618 b(42)1260 1898 y(\014ts)p 1387 1898 V 32 w(read)p 1591 1898 V 33 w(record)646 b(36)1260 2011 y(\014ts)p 1387 2011 V 32 w(read)p 1591 2011 V 33 w(subset)p 1873 2011 V 32 w(TYP)250 b(98)31 b(103)1260 2124 y(\014ts)p 1387 2124 V 32 w(read)p 1591 2124 V 33 w(subsetn)m(ull)p 2024 2124 V 30 w(TYP)101 b(98)31 b(103)1260 2237 y(\014ts)p 1387 2237 V 32 w(read)p 1591 2237 V 33 w(tbl)p 1736 2237 V 32 w(co)s(ord)530 b(72)1260 2349 y(\014ts)p 1387 2349 V 32 w(read)p 1591 2349 V 33 w(tblb)m(ytes)f(100) 1260 2462 y(\014ts)p 1387 2462 V 32 w(read)p 1591 2462 V 33 w(tdim)706 b(48)1260 2575 y(\014ts)p 1387 2575 V 32 w(remo)m(v)m(e)p 1698 2575 V 34 w(group)558 b(77)1260 2688 y(\014ts)p 1387 2688 V 32 w(remo)m(v)m(e)p 1698 2688 V 34 w(mem)m(b)s(er)467 b(79)1260 2801 y(\014ts)p 1387 2801 V 32 w(reop)s(en)p 1685 2801 V 32 w(\014le)684 b(82)1260 2914 y(\014ts)p 1387 2914 V 32 w(rep)s(ort)p 1665 2914 V 32 w(error)628 b(30)1260 3027 y(\014ts)p 1387 3027 V 32 w(resize)p 1637 3027 V 33 w(img)701 b(85)1260 3140 y(\014ts)p 1387 3140 V 32 w(select)p 1636 3140 V 33 w(ro)m(ws)669 b(52)1260 3253 y(\014ts)p 1387 3253 V 32 w(set)p 1530 3253 V 33 w(atbln)m(ull)647 b(95)1260 3366 y(\014ts)p 1387 3366 V 32 w(set)p 1530 3366 V 33 w(bscale)717 b(94)1260 3479 y(\014ts)p 1387 3479 V 32 w(set)p 1530 3479 V 33 w(btbln)m(ull)641 b(95)1260 3591 y(\014ts)p 1387 3591 V 32 w(set)p 1530 3591 V 33 w(compression)p 2045 3591 V 32 w(t)m(yp)s(e)267 b(44)1260 3704 y(\014ts)p 1387 3704 V 32 w(set)p 1530 3704 V 33 w(hdrsize)675 b(86)1260 3817 y(\014ts)p 1387 3817 V 32 w(set)p 1530 3817 V 33 w(hdustruc)604 b(86)1260 3930 y(\014ts)p 1387 3930 V 32 w(set)p 1530 3930 V 33 w(imgn)m(ull)657 b(95)1260 4043 y(\014ts)p 1387 4043 V 32 w(set)p 1530 4043 V 33 w(noise)p 1761 4043 V 33 w(bits)576 b(44)1260 4156 y(\014ts)p 1387 4156 V 32 w(set)p 1530 4156 V 33 w(tile)p 1690 4156 V 32 w(dim)643 b(44)1260 4269 y(\014ts)p 1387 4269 V 32 w(set)p 1530 4269 V 33 w(tscale)733 b(94)1260 4382 y(\014ts)p 1387 4382 V 32 w(split)p 1593 4382 V 31 w(names)646 b(56)1260 4495 y(\014ts)p 1387 4495 V 32 w(str2date)776 b(55)1260 4608 y(\014ts)p 1387 4608 V 32 w(str2time)770 b(55)1260 4721 y(\014ts)p 1387 4721 V 32 w(test)p 1565 4721 V 34 w(expr)744 b(53)1260 4833 y(\014ts)p 1387 4833 V 32 w(test)p 1565 4833 V 34 w(heap)686 b(100)1260 4946 y(\014ts)p 1387 4946 V 32 w(test)p 1565 4946 V 34 w(k)m(eyw)m(ord)591 b(57)1260 5059 y(\014ts)p 1387 5059 V 32 w(test)p 1565 5059 V 34 w(record)671 b(57)1260 5172 y(\014ts)p 1387 5172 V 32 w(time2str)770 b(55)1260 5285 y(\014ts)p 1387 5285 V 32 w(transfer)p 1726 5285 V 32 w(mem)m(b)s(er)441 b(79)1260 5398 y(\014ts)p 1387 5398 V 32 w(up)s(date)p 1695 5398 V 32 w(card)619 b(38)1260 5511 y(\014ts)p 1387 5511 V 32 w(up)s(date)p 1695 5511 V 32 w(c)m(hksum)492 b(54)1260 5624 y(\014ts)p 1387 5624 V 32 w(up)s(date)p 1695 5624 V 32 w(k)m(ey)658 b(37)1260 5737 y(\014ts)p 1387 5737 V 32 w(up)s(date)p 1695 5737 V 32 w(k)m(ey)p 1860 5737 V 34 w(n)m(ull)473 b(38)1260 5850 y(\014ts)p 1387 5850 V 32 w(up)s(date)p 1695 5850 V 32 w(k)m(ey)p 1860 5850 V 34 w(TYP)428 b(93)2723 543 y(\014ts)p 2850 543 V 33 w(upp)s(ercase)515 b(56)2723 656 y(\014ts)p 2850 656 V 33 w(url)p 2996 656 V 31 w(t)m(yp)s(e)590 b(33)2723 769 y(\014ts)p 2850 769 V 33 w(v)m(erify)p 3106 769 V 32 w(c)m(hksum)354 b(54)2723 882 y(\014ts)p 2850 882 V 33 w(v)m(erify)p 3106 882 V 32 w(group)425 b(78)2723 995 y(\014ts)p 2850 995 V 33 w(w)m(orld)p 3104 995 V 32 w(to)p 3216 995 V 33 w(pix)417 b(73)2723 1107 y(\014ts)p 2850 1107 V 33 w(write)p 3086 1107 V 32 w(2d)p 3214 1107 V 33 w(TYP)348 b(97)2723 1220 y(\014ts)p 2850 1220 V 33 w(write)p 3086 1220 V 32 w(3d)p 3214 1220 V 33 w(TYP)g(97)2723 1333 y(\014ts)p 2850 1333 V 33 w(write)p 3086 1333 V 32 w(atblhdr)378 b(87)2723 1446 y(\014ts)p 2850 1446 V 33 w(write)p 3086 1446 V 32 w(btblhdr)372 b(87)2723 1559 y(\014ts)p 2850 1559 V 33 w(write)p 3086 1559 V 32 w(c)m(hksum)i(53)2723 1672 y(\014ts)p 2850 1672 V 33 w(write)p 3086 1672 V 32 w(col)562 b(50)2723 1785 y(\014ts)p 2850 1785 V 33 w(write)p 3086 1785 V 32 w(col)p 3229 1785 V 33 w(bit)371 b(101)2723 1898 y(\014ts)p 2850 1898 V 33 w(write)p 3086 1898 V 32 w(col)p 3229 1898 V 33 w(TYP)287 b(100)2723 2011 y(\014ts)p 2850 2011 V 33 w(write)p 3086 2011 V 32 w(col)p 3229 2011 V 33 w(n)m(ull)378 b(50)2723 2124 y(\014ts)p 2850 2124 V 33 w(write)p 3086 2124 V 32 w(coln)m(ull)411 b(50)2723 2237 y(\014ts)p 2850 2237 V 33 w(write)p 3086 2237 V 32 w(coln)m(ull)p 3380 2237 V 31 w(TYP)138 b(101)2723 2349 y(\014ts)p 2850 2349 V 33 w(write)p 3086 2349 V 32 w(commen)m(t)313 b(38)2723 2462 y(\014ts)p 2850 2462 V 33 w(write)p 3086 2462 V 32 w(date)502 b(38)2723 2575 y(\014ts)p 2850 2575 V 33 w(write)p 3086 2575 V 32 w(descript)312 b(102)2723 2688 y(\014ts)p 2850 2688 V 33 w(write)p 3086 2688 V 32 w(errmark)356 b(30)2723 2801 y(\014ts)p 2850 2801 V 33 w(write)p 3086 2801 V 32 w(errmsg)404 b(56)2723 2914 y(\014ts)p 2850 2914 V 33 w(write)p 3086 2914 V 32 w(grphdr)f(87)2723 3027 y(\014ts)p 2850 3027 V 33 w(write)p 3086 3027 V 32 w(grppar)p 3382 3027 V 32 w(TYP)181 b(97)2723 3140 y(\014ts)p 2850 3140 V 33 w(write)p 3086 3140 V 32 w(history)396 b(38)2723 3253 y(\014ts)p 2850 3253 V 33 w(write)p 3086 3253 V 32 w(img)526 b(96)2723 3366 y(\014ts)p 2850 3366 V 33 w(write)p 3086 3366 V 32 w(img)p 3265 3366 V 32 w(n)m(ull)343 b(97)2723 3479 y(\014ts)p 2850 3479 V 33 w(write)p 3086 3479 V 32 w(img)p 3265 3479 V 32 w(TYP)298 b(96)2723 3591 y(\014ts)p 2850 3591 V 33 w(write)p 3086 3591 V 32 w(imghdr)388 b(87)2723 3704 y(\014ts)p 2850 3704 V 33 w(write)p 3086 3704 V 32 w(imgn)m(ull)375 b(96)2723 3817 y(\014ts)p 2850 3817 V 33 w(write)p 3086 3817 V 32 w(imgn)m(ull)p 3416 3817 V 30 w(TYP)149 b(96)2723 3930 y(\014ts)p 2850 3930 V 33 w(write)p 3086 3930 V 32 w(k)m(ey)540 b(37)2723 4043 y(\014ts)p 2850 4043 V 33 w(write)p 3086 4043 V 32 w(k)m(ey)p 3251 4043 V 33 w(longstr)233 b(89)2723 4156 y(\014ts)p 2850 4156 V 33 w(write)p 3086 4156 V 32 w(k)m(ey)p 3251 4156 V 33 w(longw)m(arn)145 b(89)2723 4269 y(\014ts)p 2850 4269 V 33 w(write)p 3086 4269 V 32 w(k)m(ey)p 3251 4269 V 33 w(n)m(ull)356 b(38)2723 4382 y(\014ts)p 2850 4382 V 33 w(write)p 3086 4382 V 32 w(k)m(ey)p 3251 4382 V 33 w(template)159 b(90)2723 4495 y(\014ts)p 2850 4495 V 33 w(write)p 3086 4495 V 32 w(k)m(ey)p 3251 4495 V 33 w(triple)293 b(90)2723 4608 y(\014ts)p 2850 4608 V 33 w(write)p 3086 4608 V 32 w(k)m(ey)p 3251 4608 V 33 w(unit)344 b(39)2723 4721 y(\014ts)p 2850 4721 V 33 w(write)p 3086 4721 V 32 w(k)m(ey)p 3251 4721 V 33 w(TYP)311 b(88)2723 4833 y(\014ts)p 2850 4833 V 33 w(write)p 3086 4833 V 32 w(k)m(eys)p 3287 4833 V 33 w(TYP)275 b(89)2723 4946 y(\014ts)p 2850 4946 V 33 w(write)p 3086 4946 V 32 w(n)m(ull)p 3269 4946 V 31 w(img)344 b(41)2723 5059 y(\014ts)p 2850 5059 V 33 w(write)p 3086 5059 V 32 w(pix)548 b(41)2723 5172 y(\014ts)p 2850 5172 V 33 w(write)p 3086 5172 V 32 w(pixn)m(ull)397 b(41)2723 5285 y(\014ts)p 2850 5285 V 33 w(write)p 3086 5285 V 32 w(record)425 b(38)2723 5398 y(\014ts)p 2850 5398 V 33 w(write)p 3086 5398 V 32 w(subset)f(40)2723 5511 y(\014ts)p 2850 5511 V 33 w(write)p 3086 5511 V 32 w(subset)p 3367 5511 V 32 w(TYP)196 b(97)2723 5624 y(\014ts)p 2850 5624 V 33 w(write)p 3086 5624 V 32 w(tblb)m(ytes)308 b(100)2723 5737 y(\014ts)p 2850 5737 V 33 w(write)p 3086 5737 V 32 w(tdim)485 b(48)2723 5850 y(\014ts)p 2850 5850 V 33 w(write)p 3086 5850 V 32 w(theap)451 b(99)p eop %%Page: 149 157 149 156 bop 3764 299 a Fj(149)50 543 y(\013asfm)276 b(59)50 656 y(\013bnfm)255 b(59)50 769 y(\013calc)310 b(52)50 882 y(\013calc)p 259 882 28 4 v 33 w(rng)145 b(53)50 995 y(\013clos)314 b(33)50 1107 y(\013cmph)197 b(100)50 1220 y(\013cmps)258 b(56)50 1333 y(\013cmrk)j(30)50 1446 y(\013cmsg)j(30)50 1559 y(\013cop)m(y)280 b(34)50 1672 y(\013cp)s(cl)301 b(49)50 1785 y(\013cp)s(dt)281 b(86)50 1898 y(\013cp\015)319 b(34)50 2011 y(\013cphd)268 b(34)50 2124 y(\013cpky)274 b(89)50 2237 y(\013crhd)283 b(84)50 2349 y(\013crim)g(40)50 2462 y(\013cro)m(w)277 b(52)50 2575 y(\013crtb)299 b(46)50 2688 y(\013dcol)g(49)50 2801 y(\013delt)309 b(33)50 2914 y(\013dhdu)257 b(35)50 3027 y(\013dk)m(ey)277 b(39)50 3140 y(\013dkinit)224 b(32)50 3253 y(\013dk)m(op)s(en)175 b(30)50 3366 y(\013dopn)263 b(30)50 3479 y(\013drec)294 b(39)50 3591 y(\013dro)m(w)266 b(48)50 3704 y(\013drrg)293 b(48)50 3817 y(\013drws)272 b(48)50 3930 y(\013dsum)247 b(54)50 4043 y(\013dt2s)294 b(55)50 4156 y(\013dtdm)248 b(48)50 4269 y(\013dt)m(yp)279 b(58)50 4382 y(\013eqt)m(y)293 b(47)50 4495 y(\013esum)258 b(54)50 4608 y(\013exest)k(83)50 4721 y(\013extn)287 b(83)50 4833 y(\013\013rw)306 b(52)50 4946 y(\013\015md)283 b(33)50 5059 y(\013\015nm)g(33)50 5172 y(\013\015sh)323 b(84)50 5285 y(\013\015us)g(84)50 5398 y(\013fro)m(w)289 b(52)50 5511 y(\013g2d)p 249 5511 V 320 w(98)50 5624 y(\013g3d)p 249 5624 V 320 w(98)50 5737 y(\013gab)s(c)277 b(59)785 543 y(\013gacl)221 b(99)785 656 y(\013gb)s(cl)212 b(99)785 769 y(\013gcdw)175 b(48)785 882 y(\013gcf)264 b(51)785 995 y(\013gcf)p 956 995 V 219 w(103)785 1107 y(\013gc)m(ks)211 b(54)785 1220 y(\013gcnn)190 b(46)785 1333 y(\013gcno)196 b(46)785 1446 y(\013gcrd)205 b(36)785 1559 y(\013gcv)244 b(51)785 1672 y(\013gcv)p 976 1672 V 199 w(102)785 1785 y(\013gcx)199 b(104)785 1898 y(\013gdes)160 b(104)785 2011 y(\013gdess)124 b(104)785 2124 y(\013gerr)220 b(29)785 2237 y(\013ggp)p 984 2237 V 236 w(98)785 2349 y(\013ghad)185 b(84)785 2462 y(\013gh)m(bn)d(87)785 2575 y(\013ghdn)d(34)785 2688 y(\013ghdt)195 b(34)785 2801 y(\013ghof)208 b(84)785 2914 y(\013ghpr)194 b(87)785 3027 y(\013ghps)g(86)785 3140 y(\013ghsp)g(35)785 3253 y(\013gh)m(tb)k(87)785 3366 y(\013gics)230 b(72)785 3479 y(\013gidm)179 b(40)785 3591 y(\013gidt)220 b(40)785 3704 y(\013giet)231 b(40)785 3817 y(\013gipr)219 b(40)785 3930 y(\013gisz)230 b(40)785 4043 y(\013gk)m(cl)221 b(58)785 4156 y(\013gk)m(ey)199 b(36)785 4269 y(\013gkls)222 b(91)785 4382 y(\013gkn)p 987 4382 V 233 w(92)785 4495 y(\013gknm)157 b(57)785 4608 y(\013gky)236 b(36)785 4721 y(\013gkyn)185 b(36)785 4833 y(\013gkyt)201 b(92)785 4946 y(\013gky)p 984 4946 V 236 w(91)785 5059 y(\013gmcp)165 b(79)785 5172 y(\013gmng)160 b(79)785 5285 y(\013gmop)g(79)785 5398 y(\013gmrm)144 b(79)785 5511 y(\013gmsg)175 b(30)785 5624 y(\013gm)m(tf)196 b(79)785 5737 y(\013gncl)215 b(46)1436 543 y(\013gnrw)283 b(46)1436 656 y(\013gnxk)289 b(36)1436 769 y(\013gpf)357 b(97)1436 882 y(\013gpf)p 1618 882 V 357 w(97)1436 995 y(\013gp)m(v)340 b(97)1436 1107 y(\013gp)m(v)p 1635 1107 V 340 w(97)1436 1220 y(\013gp)m(xv)292 b(42)1436 1333 y(\013gp)m(xf)312 b(42)1436 1446 y(\013grec)320 b(36)1436 1559 y(\013grsz)k(99)1436 1672 y(\013gsdt)314 b(55)1436 1785 y(\013gsf)p 1603 1785 V 205 w(98)32 b(103)1436 1898 y(\013gstm)289 b(55)1436 2011 y(\013gsv)p 1623 2011 V 185 w(98)32 b(103)1436 2124 y(\013gtam)280 b(78)1436 2237 y(\013gtbb)254 b(100)1436 2349 y(\013gtc)m(h)313 b(76)1436 2462 y(\013gtcl)335 b(47)1436 2575 y(\013gtcm)285 b(77)1436 2688 y(\013gtcp)310 b(77)1436 2801 y(\013gtcr)325 b(76)1436 2914 y(\013gtcs)g(72)1436 3027 y(\013gtdm)274 b(48)1436 3140 y(\013gthd)299 b(59)1436 3253 y(\013gtis)339 b(76)1436 3366 y(\013gtmg)280 b(77)1436 3479 y(\013gtnm)274 b(78)1436 3591 y(\013gtop)305 b(78)1436 3704 y(\013gtrm)289 b(77)1436 3817 y(\013gtvf)325 b(78)1436 3930 y(\013gun)m(t)302 b(37)1436 4043 y(\013hdef)311 b(86)1436 4156 y(\016bin)330 b(85)1436 4269 y(\016cls)356 b(49)1436 4382 y(\016col)347 b(49)1436 4495 y(\016img)311 b(85)1436 4608 y(\016kls)348 b(90)1436 4721 y(\016kyu)311 b(91)1436 4833 y(\016ky)p 1613 4833 V 362 w(90)1436 4946 y(\016mem)266 b(82)1436 5059 y(\016nit)346 b(32)1436 5172 y(\016opn)311 b(30)1436 5285 y(\016rec)342 b(90)1436 5398 y(\016ro)m(w)314 b(48)1436 5511 y(\016tab)327 b(85)1436 5624 y(\016ter)347 b(69)1436 5737 y(\016url)e(82)2191 543 y(\013k)m(eyn)208 b(57)2191 656 y(\013mahd)169 b(33)2191 769 y(\013mcom)155 b(38)2191 882 y(\013mcrd)189 b(92)2191 995 y(\013mkls)206 b(93)2191 1107 y(\013mkyu)169 b(93)2191 1220 y(\013mky)p 2421 1220 V 220 w(93)2191 1333 y(\013mnam)144 b(39)2191 1446 y(\013mnhd)163 b(33)2191 1559 y(\013mrec)200 b(92)2191 1672 y(\013mrhd)178 b(33)2191 1785 y(\013m)m(v)m(ec)194 b(49)2191 1898 y(\013nc)m(hk)205 b(57)2191 2011 y(\013nk)m(ey)j(58)2191 2124 y(\013omem)155 b(81)2191 2237 y(\013op)s(en)202 b(30)2191 2349 y(\013p2d)p 2396 2349 V 245 w(97)2191 2462 y(\013p3d)p 2396 2462 V 245 w(97)2191 2575 y(\013p)s(c)m(ks)217 b(53)2191 2688 y(\013p)s(cl)272 b(50)2191 2801 y(\013p)s(cls)191 b(100)2191 2914 y(\013p)s(cl)p 2369 2914 V 227 w(101)2191 3027 y(\013p)s(clu)221 b(50)2191 3140 y(\013p)s(cn)247 b(50)2191 3253 y(\013p)s(cn)p 2394 3253 V 202 w(101)2191 3366 y(\013p)s(com)177 b(38)2191 3479 y(\013p)s(dat)207 b(38)2191 3591 y(\013p)s(des)166 b(102)2191 3704 y(\013pgp)p 2396 3704 V 245 w(97)2191 3817 y(\013ph)m(bn)191 b(87)2191 3930 y(\013phis)228 b(38)2191 4043 y(\013phpr)203 b(87)2191 4156 y(\013phps)g(87)2191 4269 y(\013ph)m(tb)k(87)2191 4382 y(\013pkls)231 b(89)2191 4495 y(\013pkn)p 2399 4495 V 242 w(89)2191 4608 y(\013pktp)207 b(90)2191 4721 y(\013pky)245 b(37)2191 4833 y(\013pkyt)210 b(90)2191 4946 y(\013pkyu)194 b(38)2191 5059 y(\013pky)p 2396 5059 V 245 w(88)2191 5172 y(\013plsw)213 b(89)2191 5285 y(\013pmrk)181 b(30)2191 5398 y(\013pmsg)j(56)2191 5511 y(\013pn)m(ul)216 b(95)2191 5624 y(\013ppn)239 b(96)2191 5737 y(\013ppn)p 2402 5737 V 239 w(96)2857 543 y(\013ppr)273 b(96)2857 656 y(\013pprn)222 b(41)2857 769 y(\013ppru)g(97)2857 882 y(\013ppr)p 3053 882 V 273 w(96)2857 995 y(\013pp)m(x)264 b(41)2857 1107 y(\013pp)m(xn)213 b(41)2857 1220 y(\013prec)244 b(38)2857 1333 y(\013pscl)258 b(94)2857 1446 y(\013pss)288 b(40)2857 1559 y(\013pss)p 3038 1559 V 288 w(97)2857 1672 y(\013psv)m(c)239 b(57)2857 1785 y(\013ptbb)177 b(100)2857 1898 y(\013ptdm)198 b(48)2857 2011 y(\013pthp)223 b(99)2857 2124 y(\013pun)m(t)j(39)2857 2237 y(\013rdef)256 b(86)2857 2349 y(\013reop)s(en)145 b(82)2857 2462 y(\013rprt)253 b(30)2857 2575 y(\013rsim)237 b(85)2857 2688 y(\013rtnm)213 b(83)2857 2801 y(\013rwrg)228 b(61)2857 2914 y(\013s2dt)244 b(55)2857 3027 y(\013s2tm)219 b(55)2857 3140 y(\013sn)m(ul)250 b(95)2857 3253 y(\013sro)m(w)231 b(52)2857 3366 y(\013texp)237 b(53)2857 3479 y(\013thdu)223 b(33)2857 3591 y(\013theap)143 b(100)2857 3704 y(\013tk)m(ey)243 b(57)2857 3817 y(\013tm2s)219 b(55)2857 3930 y(\013tn)m(ul)251 b(95)2857 4043 y(\013topn)229 b(30)2857 4156 y(\013tplt)264 b(82)2857 4269 y(\013trec)c(57)2857 4382 y(\013tscl)274 b(94)2857 4495 y(\013ucrd)233 b(38)2857 4608 y(\013ukls)250 b(93)2857 4721 y(\013uky)264 b(37)2857 4833 y(\013ukyu)213 b(38)2857 4946 y(\013uky)p 3062 4946 V 264 w(93)2857 5059 y(\013up)s(c)m(h)218 b(56)2857 5172 y(\013up)s(c)m(k)j(54)2857 5285 y(\013urlt)263 b(33)2857 5398 y(\013v)m(c)m(ks)245 b(54)2857 5511 y(\013v)m(ers)254 b(56)2857 5624 y(\013wldp)217 b(73)2857 5737 y(\013xyp)m(x)i(73)p eop %%Page: 150 158 150 157 bop 0 299 a Fj(150)2084 b Fh(APPENDIX)31 b(A.)61 b(INDEX)31 b(OF)f(R)m(OUTINES)p eop %%Page: 151 159 151 158 bop 0 1225 a Fg(App)5 b(endix)65 b(B)0 1687 y Fm(P)-6 b(arameter)77 b(De\014nitions)0 2180 y Fe(anynul)142 b(-)47 b(set)g(to)g(TRUE)g(\(=1\))f(if)i(any)e(returned)g(values)g(are) h(undefined,)e(else)i(FALSE)0 2293 y(array)190 b(-)47 b(array)f(of)i(numerical)d(data)h(values)h(to)g(read)f(or)i(write)0 2406 y(ascii)190 b(-)47 b(encoded)f(checksum)f(string)0 2518 y(binspec)94 b(-)47 b(the)g(input)f(table)h(binning)e(specifier)0 2631 y(bitpix)142 b(-)47 b(bits)g(per)g(pixel.)f(The)h(following)e (symbolic)g(mnemonics)h(are)h(predefined:)716 2744 y(BYTE_IMG)141 b(=)i(8)47 b(\(unsigned)f(char\))716 2857 y(SHORT_IMG)93 b(=)i(16)47 b(\(signed)f(short)g(integer\))716 2970 y(LONG_IMG)141 b(=)95 b(32)47 b(\(signed)f(long)h(integer\))716 3083 y(LONGLONG_IMG)d(=)96 b(64)47 b(\(signed)f(long)g(64-bit)g(integer\)) 716 3196 y(FLOAT_IMG)93 b(=)47 b(-32)g(\(float\))716 3309 y(DOUBLE_IMG)e(=)i(-64)g(\(double\).)525 3422 y(The)g (LONGLONG_IMG)d(type)j(is)g(experimental)e(and)i(is)g(not)g(officially) 525 3535 y(recognized)e(in)i(the)g(FITS)g(Standard)e(document.)525 3648 y(Two)i(additional)e(values,)h(USHORT_IMG)f(and)i(ULONG_IMG)e(are) i(also)f(available)525 3760 y(for)h(creating)e(unsigned)h(integer)g (images.)93 b(These)47 b(are)g(equivalent)e(to)525 3873 y(creating)h(a)h(signed)f(integer)g(image)g(with)h(BZERO)f(offset)g (keyword)g(values)525 3986 y(of)h(32768)g(or)g(2147483648,)d (respectively,)h(which)h(is)h(the)g(convention)e(that)525 4099 y(FITS)i(uses)f(to)h(store)g(unsigned)e(integers.)0 4212 y(card)238 b(-)47 b(header)f(record)g(to)h(be)h(read)e(or)h (written)f(\(80)h(char)g(max,)f(null-terminated\))0 4325 y(casesen)94 b(-)47 b(CASESEN)f(\(=1\))g(for)h(case-sensitive)d(string) i(matching,)g(else)g(CASEINSEN)g(\(=0\))0 4438 y(cmopt)190 b(-)47 b(grouping)f(table)g("compact")f(option)h(parameter.)f(Allowed)h (values)g(are:)525 4551 y(OPT_CMT_MBR)f(and)i(OPT_CMT_MBR_DEL.)0 4664 y(colname)94 b(-)47 b(name)g(of)g(the)g(column)f (\(null-terminated\))0 4777 y(colnum)142 b(-)47 b(column)f(number)g (\(first)g(column)g(=)i(1\))0 4890 y(colspec)94 b(-)47 b(the)g(input)f(file)h(column)f(specification;)e(used)j(to)g(delete,)f (create,)f(or)j(rename)525 5002 y(table)e(columns)0 5115 y(comment)94 b(-)47 b(the)g(keyword)f(comment)g(field)g(\(72)h(char)f (max,)h(null-terminated\))0 5228 y(complm)142 b(-)47 b(should)f(the)h(checksum)f(be)h(complemented?)0 5341 y(comptype)f(-)h(compression)e(algorithm)g(to)i(use:)g(GZIP_1,)f (RICE_1,)f(or)j(PLIO_1)0 5454 y(coordtype-)d(type)i(of)g(coordinate)e (projection)g(\(-SIN,)h(-TAN,)g(-ARC,)h(-NCP,)525 5567 y(-GLS,)f(-MER,)h(or)g(-AIT\))0 5680 y(cpopt)190 b(-)47 b(grouping)f(table)g(copy)h(option)f(parameter.)f(Allowed)g(values)i (are:)1882 5942 y Fj(151)p eop %%Page: 152 160 152 159 bop 0 299 a Fj(152)1822 b Fh(APPENDIX)31 b(B.)61 b(P)-8 b(ARAMETER)30 b(DEFINITIONS)525 555 y Fe(OPT_GCP_GPT,)44 b(OPT_GCP_MBR,)h(OPT_GCP_ALL,)f(OPT_MCP_ADD,)h(OPT_MCP_NADD,)525 668 y(OPT_MCP_REPL,)f(amd)j(OPT_MCP_MOV.)0 781 y(create_col-)e(If)i (TRUE,)f(then)h(insert)f(a)h(new)g(column)f(in)i(the)f(table,)f (otherwise)525 894 y(overwrite)f(the)i(existing)f(column.)0 1007 y(current)94 b(-)47 b(if)g(TRUE,)g(then)f(the)h(current)f(HDU)h (will)f(be)i(copied)0 1120 y(dataok)142 b(-)47 b(was)g(the)g(data)f (unit)h(verification)e(successful)g(\(=1\))h(or)525 1233 y(not)h(\(=)g(-1\).)94 b(Equals)47 b(zero)f(if)h(the)g(DATASUM)f (keyword)g(is)h(not)g(present.)0 1346 y(datasum)94 b(-)47 b(32-bit)f(1's)h(complement)e(checksum)h(for)g(the)h(data)g(unit)0 1458 y(dataend)94 b(-)47 b(address)f(\(in)h(bytes\))f(of)h(the)g(end)g (of)g(the)g(HDU)0 1571 y(datastart-)e(address)h(\(in)h(bytes\))f(of)h (the)g(start)f(of)h(the)g(data)g(unit)0 1684 y(datatype)f(-)h (specifies)e(the)i(data)g(type)f(of)i(the)f(value.)93 b(Allowed)46 b(value)h(are:)94 b(TSTRING,)525 1797 y(TLOGICAL,)45 b(TBYTE,)h(TSBYTE,)g(TSHORT,)g(TUSHORT,)g(TINT,)g(TUINT,)g(TLONG,)g (TULONG,)525 1910 y(TFLOAT,)g(TDOUBLE,)f(TCOMPLEX,)h(and)h(TDBLCOMPLEX) 0 2023 y(datestr)94 b(-)47 b(FITS)g(date/time)e(string:)h ('YYYY-MM-DDThh:mm:ss.dd)o(d',)41 b('YYYY-MM-dd',)525 2136 y(or)47 b('dd/mm/yy')0 2249 y(day)286 b(-)47 b(calendar)f(day)g (\(UTC\))h(\(1-31\))0 2362 y(decimals)f(-)h(number)f(of)h(decimal)f (places)g(to)h(be)h(displayed)0 2475 y(deltasize)d(-)j(increment)d(for) i(allocating)e(more)i(memory)0 2588 y(dim1)238 b(-)47 b(declared)f(size)g(of)h(the)g(first)g(dimension)e(of)i(the)g(image)f (or)i(cube)e(array)0 2700 y(dim2)238 b(-)47 b(declared)f(size)g(of)h (the)g(second)f(dimension)g(of)h(the)g(data)f(cube)h(array)0 2813 y(dispwidth)e(-)j(display)e(width)g(of)h(a)h(column)e(=)h(length)f (of)h(string)f(that)h(will)g(be)g(read)0 2926 y(dtype)190 b(-)47 b(data)g(type)f(of)h(the)g(keyword)f(\('C',)h('L',)f('I',)h('F') g(or)g('X'\))764 3039 y(C)g(=)h(character)d(string)764 3152 y(L)i(=)h(logical)764 3265 y(I)f(=)h(integer)764 3378 y(F)f(=)h(floating)d(point)h(number)764 3491 y(X)h(=)h(complex,)d (e.g.,)h("\(1.23,)g(-4.56\)")0 3604 y(err_msg)94 b(-)47 b(error)f(message)g(on)h(the)g(internal)f(stack)g(\(80)h(chars)f(max\)) 0 3717 y(err_text)g(-)h(error)f(message)g(string)g(corresponding)e(to)k (error)e(number)g(\(30)h(chars)f(max\))0 3830 y(exact)190 b(-)47 b(TRUE)g(\(=1\))f(if)h(the)g(strings)f(match)h(exactly;)525 3942 y(FALSE)f(\(=0\))h(if)g(wildcards)e(are)i(used)0 4055 y(exclist)94 b(-)47 b(array)f(of)i(pointers)d(to)i(keyword)f (names)g(to)i(be)f(excluded)e(from)i(search)0 4168 y(exists)142 b(-)47 b(flag)g(indicating)e(whether)g(the)i(file)g(or)g(compressed)e (file)i(exists)f(on)h(disk)0 4281 y(expr)238 b(-)47 b(boolean)f(or)h (arithmetic)e(expression)0 4394 y(extend)142 b(-)47 b(TRUE)g(\(=1\))f (if)h(FITS)g(file)g(may)g(have)f(extensions,)f(else)i(FALSE)f(\(=0\))0 4507 y(extname)94 b(-)47 b(value)f(of)i(the)e(EXTNAME)g(keyword)g (\(null-terminated\))0 4620 y(extspec)94 b(-)47 b(the)g(extension)e(or) i(HDU)g(specifier;)e(a)j(number)e(or)h(name,)f(version,)g(and)h(type)0 4733 y(extver)142 b(-)47 b(value)f(of)i(the)e(EXTVER)h(keyword)e(=)j (integer)e(version)f(number)0 4846 y(filename)h(-)h(full)g(name)f(of)h (the)g(FITS)g(file,)f(including)g(optional)f(HDU)i(and)g(filtering)e (specs)0 4959 y(filetype)h(-)h(type)g(of)g(file)f(\(file://,)g(ftp://,) g(http://,)f(etc.\))0 5072 y(filter)142 b(-)47 b(the)g(input)f(file)h (filtering)e(specifier)0 5185 y(firstchar-)g(starting)h(byte)g(in)h (the)g(row)g(\(first)f(byte)h(of)g(row)g(=)g(1\))0 5297 y(firstfailed)e(-)i(member)f(HDU)h(ID)g(\(if)g(positive\))f(or)h (grouping)e(table)i(GRPIDn)f(index)525 5410 y(value)g(\(if)h (negative\))f(that)g(failed)g(grouping)g(table)g(verification.)0 5523 y(firstelem-)f(first)h(element)g(in)h(a)h(vector)e(\(ignored)f (for)i(ASCII)g(tables\))0 5636 y(firstrow)f(-)h(starting)f(row)g (number)h(\(first)f(row)h(of)g(table)f(=)i(1\))p eop %%Page: 153 161 153 160 bop 3764 299 a Fj(153)0 555 y Fe(following-)45 b(if)i(TRUE,)g(any)f(HDUs)h(following)e(the)i(current)f(HDU)h(will)g (be)g(copied)0 668 y(fpixel)142 b(-)47 b(coordinate)e(of)i(the)g(first) f(pixel)h(to)g(be)g(read)g(or)g(written)f(in)h(the)525 781 y(FITS)g(array.)93 b(The)47 b(array)g(must)f(be)i(of)f(length)f (NAXIS)g(and)h(have)g(values)f(such)525 894 y(that)h(fpixel[0])e(is)i (in)g(the)g(range)g(1)g(to)g(NAXIS1,)f(fpixel[1])f(is)i(in)h(the)525 1007 y(range)e(1)i(to)f(NAXIS2,)f(etc.)0 1120 y(fptr)238 b(-)47 b(pointer)f(to)h(a)g('fitsfile')e(structure)h(describing)f(the)i (FITS)f(file.)0 1233 y(frac)238 b(-)47 b(factional)e(part)i(of)g(the)g (keyword)f(value)0 1346 y(gcount)142 b(-)47 b(number)f(of)h(groups)f (in)i(the)e(primary)g(array)h(\(usually)e(=)j(1\))0 1458 y(gfptr)190 b(-)47 b(fitsfile*)e(pointer)h(to)h(a)h(grouping)d(table)i (HDU.)0 1571 y(group)190 b(-)47 b(GRPIDn/GRPLCn)d(index)j(value)f (identifying)f(a)i(grouping)f(table)g(HDU,)h(or)525 1684 y(data)g(group)f(number)g(\(=0)h(for)g(non-grouped)e(data\))0 1797 y(grouptype)g(-)j(Grouping)d(table)i(parameter)e(that)i(specifies) e(the)i(columns)f(to)h(be)525 1910 y(created)f(in)h(a)g(grouping)f (table)g(HDU.)h(Allowed)f(values)g(are:)h(GT_ID_ALL_URI,)525 2023 y(GT_ID_REF,)e(GT_ID_POS,)g(GT_ID_ALL,)g(GT_ID_REF_URI,)f(and)j (GT_ID_POS_URI.)0 2136 y(grpname)94 b(-)47 b(value)f(to)i(use)e(for)h (the)g(GRPNAME)f(keyword)g(value.)0 2249 y(hdunum)142 b(-)47 b(sequence)f(number)g(of)h(the)g(HDU)g(\(Primary)e(array)i(=)g (1\))0 2362 y(hduok)190 b(-)47 b(was)g(the)g(HDU)g(verification)d (successful)h(\(=1\))i(or)525 2475 y(not)g(\(=)g(-1\).)94 b(Equals)47 b(zero)f(if)h(the)g(CHECKSUM)f(keyword)g(is)h(not)g (present.)0 2588 y(hdusum)142 b(-)47 b(32)g(bit)g(1's)g(complement)e (checksum)h(for)g(the)h(entire)f(CHDU)0 2700 y(hdutype)94 b(-)47 b(type)g(of)g(HDU:)f(IMAGE_HDU)g(\(=0\),)g(ASCII_TBL)f(\(=1\),)i (or)g(BINARY_TBL)e(\(=2\))0 2813 y(header)142 b(-)47 b(returned)f(character)f(string)h(containing)f(all)i(the)g(keyword)f (records)0 2926 y(headstart-)f(starting)h(address)f(\(in)i(bytes\))f (of)i(the)e(CHDU)0 3039 y(heapsize)g(-)h(size)g(of)g(the)g(binary)f (table)g(heap,)h(in)g(bytes)0 3152 y(history)94 b(-)47 b(the)g(HISTORY)f(keyword)g(comment)f(string)h(\(70)h(char)g(max,)g (null-terminated\))0 3265 y(hour)238 b(-)47 b(hour)g(within)f(day)h (\(UTC\))f(\(0)h(-)h(23\))0 3378 y(inc)286 b(-)47 b(sampling)f (interval)f(for)i(pixels)f(in)h(each)g(FITS)g(dimension)0 3491 y(inclist)94 b(-)47 b(array)f(of)i(pointers)d(to)i(matching)f (keyword)g(names)0 3604 y(incolnum)g(-)h(input)f(column)g(number;)g (range)h(=)g(1)h(to)f(TFIELDS)0 3717 y(infile)142 b(-)47 b(the)g(input)f(filename,)g(including)f(path)h(if)i(specified)0 3830 y(infptr)142 b(-)47 b(pointer)f(to)h(a)g('fitsfile')e(structure)h (describing)f(the)i(input)f(FITS)h(file.)0 3942 y(intval)142 b(-)47 b(integer)f(part)g(of)i(the)f(keyword)e(value)0 4055 y(iomode)142 b(-)47 b(file)g(access)f(mode:)g(either)g(READONLY)g (\(=0\))g(or)i(READWRITE)d(\(=1\))0 4168 y(keyname)94 b(-)47 b(name)g(of)g(a)g(keyword)f(\(8)h(char)g(max,)g (null-terminated\))0 4281 y(keynum)142 b(-)47 b(position)f(of)h (keyword)f(in)h(header)f(\(1st)g(keyword)g(=)i(1\))0 4394 y(keyroot)94 b(-)47 b(root)g(string)f(for)h(the)g(keyword)e(name)i (\(5)g(char)g(max,)f(null-terminated\))0 4507 y(keysexist-)f(number)h (of)h(existing)f(keyword)g(records)f(in)j(the)f(CHU)0 4620 y(keytype)94 b(-)47 b(header)f(record)g(type:)h(-1=delete;)92 b(0=append)46 b(or)h(replace;)907 4733 y(1=append;)e(2=this)h(is)h(the) g(END)g(keyword)0 4846 y(longstr)94 b(-)47 b(arbitrarily)e(long)h (string)g(keyword)g(value)h(\(null-terminated\))0 4959 y(lpixel)142 b(-)47 b(coordinate)e(of)i(the)g(last)g(pixel)f(to)h(be)g (read)g(or)g(written)f(in)h(the)525 5072 y(FITS)g(array.)93 b(The)47 b(array)g(must)f(be)i(of)f(length)f(NAXIS)g(and)h(have)g (values)f(such)525 5185 y(that)h(lpixel[0])e(is)i(in)g(the)g(range)g(1) g(to)g(NAXIS1,)f(lpixel[1])f(is)i(in)h(the)525 5297 y(range)e(1)i(to)f (NAXIS2,)f(etc.)0 5410 y(match)190 b(-)47 b(TRUE)g(\(=1\))f(if)h(the)g (2)h(strings)e(match,)g(else)g(FALSE)h(\(=0\))0 5523 y(maxdim)142 b(-)47 b(maximum)f(number)g(of)h(values)f(to)h(return)0 5636 y(member)142 b(-)47 b(row)g(number)f(of)h(a)h(grouping)d(table)i (member)f(HDU.)p eop %%Page: 154 162 154 161 bop 0 299 a Fj(154)1822 b Fh(APPENDIX)31 b(B.)61 b(P)-8 b(ARAMETER)30 b(DEFINITIONS)0 555 y Fe(memptr)142 b(-)47 b(pointer)f(to)h(the)g(a)g(FITS)g(file)g(in)g(memory)0 668 y(mem_realloc)e(-)i(pointer)f(to)h(a)h(function)d(for)i (reallocating)e(more)h(memory)0 781 y(memsize)94 b(-)47 b(size)g(of)g(the)g(memory)f(block)g(allocated)f(for)i(the)g(FITS)g (file)0 894 y(mfptr)190 b(-)47 b(fitsfile*)e(pointer)h(to)h(a)h (grouping)d(table)i(member)f(HDU.)0 1007 y(mgopt)190 b(-)47 b(grouping)f(table)g(merge)g(option)g(parameter.)f(Allowed)h (values)g(are:)525 1120 y(OPT_MRG_COPY,)e(and)j(OPT_MRG_MOV.)0 1233 y(minute)142 b(-)47 b(minute)f(within)g(hour)h(\(UTC\))f(\(0)h(-)h (59\))0 1346 y(month)190 b(-)47 b(calendar)f(month)g(\(UTC\))g(\(1)h(-) h(12\))0 1458 y(morekeys)e(-)h(space)f(in)i(the)e(header)h(for)f(this)h (many)g(more)f(keywords)0 1571 y(n_good_rows)f(-)i(number)f(of)h(rows)g (evaluating)e(to)i(TRUE)0 1684 y(namelist)f(-)h(string)f(containing)f (a)j(comma)e(or)h(space)f(delimited)g(list)g(of)i(names)0 1797 y(naxes)190 b(-)47 b(size)g(of)g(each)f(dimension)g(in)h(the)g (FITS)f(array)0 1910 y(naxis)190 b(-)47 b(number)f(of)h(dimensions)e (in)i(the)g(FITS)g(array)0 2023 y(naxis1)142 b(-)47 b(length)f(of)h (the)g(X/first)f(axis)h(of)g(the)g(FITS)f(array)0 2136 y(naxis2)142 b(-)47 b(length)f(of)h(the)g(Y/second)f(axis)g(of)i(the)e (FITS)h(array)0 2249 y(naxis3)142 b(-)47 b(length)f(of)h(the)g(Z/third) f(axis)h(of)g(the)g(FITS)f(array)0 2362 y(nchars)142 b(-)47 b(number)f(of)h(characters)e(to)i(read)g(or)g(write)0 2475 y(nelements-)e(number)h(of)h(data)g(elements)e(to)j(read)e(or)h (write)0 2588 y(newfptr)94 b(-)47 b(returned)f(pointer)f(to)j(the)e (reopened)g(file)0 2700 y(newveclen-)f(new)i(value)f(for)h(the)g (column)f(vector)g(repeat)g(parameter)0 2813 y(nexc)238 b(-)47 b(number)f(of)h(names)g(in)g(the)g(exclusion)e(list)i(\(may)f(=) i(0\))0 2926 y(nfound)142 b(-)47 b(number)f(of)h(keywords)f(found)g (\(highest)g(keyword)g(number\))0 3039 y(nkeys)190 b(-)47 b(number)f(of)h(keywords)f(in)h(the)g(sequence)0 3152 y(ninc)238 b(-)47 b(number)f(of)h(names)g(in)g(the)g(inclusion)e(list)0 3265 y(nmembers)h(-)h(Number)f(of)h(grouping)f(table)g(members)g (\(NAXIS2)g(value\).)0 3378 y(nmove)190 b(-)47 b(number)f(of)h(HDUs)g (to)g(move)g(\(+)g(or)g(-\),)g(relative)f(to)h(current)f(position)0 3491 y(nocomments)f(-)i(if)h(equal)e(to)h(TRUE,)g(then)f(no)h (commentary)e(keywords)h(will)h(be)g(copied)0 3604 y(noisebits-)e (number)h(of)h(bits)g(to)g(ignore)f(when)h(compressing)e(floating)g (point)h(images)0 3717 y(nrows)190 b(-)47 b(number)f(of)h(rows)g(in)g (the)g(table)0 3830 y(nstart)142 b(-)47 b(first)f(integer)g(value)0 3942 y(nullarray-)f(set)i(to)g(TRUE)g(\(=1\))f(if)i(corresponding)c (data)i(element)g(is)h(undefined)0 4055 y(nulval)142 b(-)47 b(numerical)e(value)i(to)g(represent)e(undefined)g(pixels)0 4168 y(nulstr)142 b(-)47 b(character)e(string)h(used)h(to)g(represent)e (undefined)h(values)g(in)h(ASCII)f(table)0 4281 y(numval)142 b(-)47 b(numerical)e(data)i(value,)f(of)h(the)g(appropriate)e(data)h (type)0 4394 y(offset)142 b(-)95 b(byte)46 b(offset)g(in)i(the)f(heap)f (to)h(the)g(first)g(element)e(of)j(the)f(vector)0 4507 y(openfptr)f(-)h(pointer)f(to)h(a)g(currently)f(open)g(FITS)h(file)0 4620 y(overlap)94 b(-)47 b(number)f(of)h(bytes)g(in)g(the)g(binary)f (table)g(heap)h(pointed)f(to)h(by)g(more)g(than)f(1)525 4733 y(descriptor)0 4846 y(outcolnum-)f(output)h(column)g(number;)g (range)g(=)i(1)f(to)g(TFIELDS)f(+)i(1)0 4959 y(outfile)94 b(-)47 b(and)g(optional)e(output)i(filename;)e(the)i(input)f(file)h (will)f(be)i(copied)e(to)h(this)f(prior)525 5072 y(to)h(opening)f(the)h (file)0 5185 y(outfptr)94 b(-)47 b(pointer)f(to)h(a)g('fitsfile')e (structure)h(describing)f(the)i(output)f(FITS)g(file.)0 5297 y(pcount)142 b(-)47 b(value)f(of)i(the)e(PCOUNT)h(keyword)e(=)j (size)e(of)i(binary)e(table)g(heap)0 5410 y(previous)g(-)h(if)g(TRUE,)g (any)f(previous)g(HDUs)h(in)g(the)g(input)f(file)h(will)f(be)i(copied.) 0 5523 y(repeat)142 b(-)47 b(length)f(of)h(column)f(vector)g(\(e.g.)h (12J\);)f(==)h(1)h(for)f(ASCII)f(table)0 5636 y(rmopt)190 b(-)47 b(grouping)f(table)g(remove)g(option)g(parameter.)f(Allowed)h (values)g(are:)p eop %%Page: 155 163 155 162 bop 3764 299 a Fj(155)525 555 y Fe(OPT_RM_GPT,)45 b(OPT_RM_ENTRY,)f(OPT_RM_MBR,)h(and)i(OPT_RM_ALL.)0 668 y(rootname)f(-)h(root)g(filename,)e(minus)h(any)h(extension)e(or)j (filtering)d(specifications)0 781 y(rot)286 b(-)47 b(celestial)e (coordinate)g(rotation)h(angle)g(\(degrees\))0 894 y(rowlen)142 b(-)47 b(length)f(of)h(a)h(table)e(row,)h(in)g(characters)e(or)i(bytes) 0 1007 y(rowlist)94 b(-)47 b(sorted)f(list)h(of)g(row)g(numbers)f(to)h (be)g(deleted)f(from)g(the)h(table)0 1120 y(rownum)142 b(-)47 b(number)f(of)h(the)g(row)g(\(first)f(row)h(=)h(1\))0 1233 y(rowrange)e(-)h(list)g(of)g(rows)f(or)i(row)f(ranges:)e ('3,6-8,12,56-80')f(or)j('500-')0 1346 y(row_status)e(-)i(array)g(of)g (True/False)e(results)h(for)h(each)f(row)h(that)g(was)g(evaluated)0 1458 y(scale)190 b(-)47 b(linear)f(scaling)g(factor;)g(true)g(value)h (=)g(\(FITS)g(value\))f(*)h(scale)f(+)i(zero)0 1571 y(second)142 b(-)47 b(second)f(within)g(minute)g(\(0)h(-)h(60.9999999999\))c(\(leap) i(second!\))0 1684 y(simple)142 b(-)47 b(TRUE)g(\(=1\))f(if)h(FITS)g (file)g(conforms)e(to)i(the)g(Standard,)f(else)g(FALSE)h(\(=0\))0 1797 y(space)190 b(-)47 b(number)f(of)h(blank)g(spaces)f(to)h(leave)f (between)g(ASCII)g(table)h(columns)0 1910 y(status)142 b(-)47 b(returned)f(error)g(status)g(code)h(\(0)g(=)g(OK\))0 2023 y(sum)286 b(-)47 b(32)g(bit)g(unsigned)f(checksum)f(value)0 2136 y(tbcol)190 b(-)47 b(byte)g(position)e(in)i(row)g(to)g(start)g(of) g(column)f(\(1st)h(col)g(has)g(tbcol)f(=)h(1\))0 2249 y(tdisp)190 b(-)47 b(Fortran)f(style)g(display)g(format)g(for)h(the)g (table)f(column)0 2362 y(tdimstr)94 b(-)47 b(the)g(value)f(of)h(the)g (TDIMn)g(keyword)0 2475 y(templt)142 b(-)47 b(template)f(string)g(used) g(in)h(comparison)e(\(null-terminated\))0 2588 y(tfields)94 b(-)47 b(number)f(of)h(fields)f(\(columns\))g(in)h(the)g(table)0 2700 y(tfopt)190 b(-)47 b(grouping)f(table)g(member)g(transfer)g (option)g(parameter.)f(Allowed)g(values)i(are:)525 2813 y(OPT_MCP_ADD,)d(and)j(OPT_MCP_MOV.)0 2926 y(tform)190 b(-)47 b(format)f(of)h(the)g(column)f(\(null-terminated\);)d(allowed)j (values)g(are:)525 3039 y(ASCII)g(tables:)94 b(Iw,)47 b(Aw,)g(Fww.dd,)f(Eww.dd,)f(or)j(Dww.dd)525 3152 y(Binary)e(tables:)g (rL,)h(rX,)g(rB,)g(rI,)g(rJ,)f(rA,)h(rAw,)g(rE,)g(rD,)g(rC,)g(rM)525 3265 y(where)f('w'=width)g(of)h(the)g(field,)f('d'=no.)g(of)h (decimals,)e('r'=repeat)g(count.)525 3378 y(Variable)h(length)g(array)g (columns)g(are)h(denoted)f(by)h(a)g('1P')g(before)f(the)h(data)f(type) 525 3491 y(character)f(\(e.g.,)h('1PJ'\).)94 b(When)47 b(creating)e(a)j(binary)e(table,)g(2)h(addition)f(tform)525 3604 y(data)h(type)f(codes)h(are)g(recognized)e(by)i(CFITSIO:)e('rU')i (and)g('rV')f(for)h(unsigned)525 3717 y(16-bit)f(and)h(unsigned)f (32-bit)g(integer,)f(respectively.)0 3942 y(theap)190 b(-)47 b(zero)g(indexed)e(byte)i(offset)f(of)h(starting)f(address)g(of) h(the)g(heap)525 4055 y(relative)f(to)h(the)g(beginning)e(of)i(the)g (binary)f(table)g(data)0 4168 y(tilesize)g(-)h(array)f(of)i(length)e (NAXIS)g(that)h(specifies)e(the)i(dimensions)e(of)525 4281 y(the)i(image)f(compression)f(tiles)0 4394 y(ttype)190 b(-)47 b(label)f(or)i(name)e(for)h(table)f(column)h (\(null-terminated\))0 4507 y(tunit)190 b(-)47 b(physical)f(unit)g(for) h(table)f(column)h(\(null-terminated\))0 4620 y(typechar)f(-)h (symbolic)f(code)g(of)h(the)g(table)g(column)f(data)g(type)0 4733 y(typecode)g(-)h(data)g(type)f(code)h(of)g(the)g(table)f(column.) 94 b(The)47 b(negative)e(of)525 4846 y(the)i(value)f(indicates)g(a)h (variable)f(length)g(array)g(column.)764 4959 y(Datatype)618 b(typecode)189 b(Mnemonic)764 5072 y(bit,)46 b(X)907 b(1)381 b(TBIT)764 5185 y(byte,)46 b(B)811 b(11)381 b(TBYTE)764 5297 y(logical,)45 b(L)668 b(14)381 b(TLOGICAL)764 5410 y(ASCII)46 b(character,)f(A)286 b(16)381 b(TSTRING)764 5523 y(short)46 b(integer,)g(I)381 b(21)g(TSHORT)764 5636 y(integer,)45 b(J)668 b(41)381 b(TINT32BIT)p eop %%Page: 156 164 156 163 bop 0 299 a Fj(156)1822 b Fh(APPENDIX)31 b(B.)61 b(P)-8 b(ARAMETER)30 b(DEFINITIONS)764 555 y Fe(long)46 b(long)h(integer,)e(K)191 b(81)381 b(TLONGLONG)764 668 y(real,)46 b(E)811 b(42)381 b(TFLOAT)764 781 y(double)46 b(precision,)f(D)238 b(82)381 b(TDOUBLE)764 894 y(complex,)45 b(C)668 b(83)381 b(TCOMPLEX)764 1007 y(double)46 b(complex,)f(M)286 b(163)381 b(TDBLCOMPLEX)620 1120 y(The)47 b(TLONGLONG)f(column)g(type)g (is)i(experimental)c(and)j(is)g(not)620 1233 y(recognized)e(in)j(the)f (official)e(FITS)i(Standard)e(document)0 1346 y(unit)238 b(-)47 b(the)g(physical)e(unit)i(string)f(\(e.g.,)g('km/s'\))g(for)h(a) g(keyword)0 1458 y(unused)142 b(-)47 b(number)f(of)h(unused)f(bytes)h (in)g(the)g(binary)f(table)g(heap)0 1571 y(urltype)94 b(-)47 b(the)g(file)g(type)f(of)h(the)g(FITS)g(file)g(\(file://,)e (ftp://,)h(mem://,)f(etc.\))0 1684 y(validheap-)g(returned)h(value)g(=) h(FALSE)g(if)g(any)g(of)g(the)g(variable)e(length)i(array)525 1797 y(address)f(are)h(outside)f(the)g(valid)h(range)f(of)h(addresses)f (in)h(the)g(heap)0 1910 y(value)190 b(-)47 b(the)g(keyword)f(value)g (string)g(\(70)h(char)g(max,)f(null-terminated\))0 2023 y(version)94 b(-)47 b(current)f(version)g(number)g(of)h(the)g(CFITSIO)f (library)0 2136 y(width)190 b(-)47 b(width)f(of)i(the)e(character)g (string)g(field)0 2249 y(xcol)238 b(-)47 b(number)f(of)h(the)g(column)f (containing)f(the)i(X)h(coordinate)d(values)0 2362 y(xinc)238 b(-)47 b(X)g(axis)g(coordinate)e(increment)g(at)j(reference)d(pixel)h (\(deg\))0 2475 y(xpix)238 b(-)47 b(X)g(axis)g(pixel)f(location)0 2588 y(xpos)238 b(-)47 b(X)g(axis)g(celestial)e(coordinate)g(\(usually) h(RA\))h(\(deg\))0 2700 y(xrefpix)94 b(-)47 b(X)g(axis)g(reference)e (pixel)i(array)f(location)0 2813 y(xrefval)94 b(-)47 b(X)g(axis)g(coordinate)e(value)h(at)i(the)f(reference)e(pixel)h (\(deg\))0 2926 y(ycol)238 b(-)47 b(number)f(of)h(the)g(column)f (containing)f(the)i(X)h(coordinate)d(values)0 3039 y(year)238 b(-)47 b(calendar)f(year)g(\(e.g.)h(1999,)f(2000,)g(etc\))0 3152 y(yinc)238 b(-)47 b(Y)g(axis)g(coordinate)e(increment)g(at)j (reference)d(pixel)h(\(deg\))0 3265 y(ypix)238 b(-)47 b(y)g(axis)g(pixel)f(location)0 3378 y(ypos)238 b(-)47 b(y)g(axis)g(celestial)e(coordinate)g(\(usually)h(DEC\))h(\(deg\))0 3491 y(yrefpix)94 b(-)47 b(Y)g(axis)g(reference)e(pixel)i(array)f (location)0 3604 y(yrefval)94 b(-)47 b(Y)g(axis)g(coordinate)e(value)h (at)i(the)f(reference)e(pixel)h(\(deg\))0 3717 y(zero)238 b(-)47 b(scaling)f(offset;)g(true)g(value)h(=)g(\(FITS)f(value\))h(*)g (scale)f(+)i(zero)p eop %%Page: 157 165 157 164 bop 0 1225 a Fg(App)5 b(endix)65 b(C)0 1687 y Fm(CFITSIO)76 b(Error)h(Status)h(Co)6 b(des)0 2180 y Fj(The)28 b(follo)m(wing)e(table)i(lists)f(all)g(the)h(error)g(status)g (co)s(des)g(used)f(b)m(y)h(CFITSIO.)f(Programmers)h(are)g(encouraged)0 2293 y(to)37 b(use)e(the)h(sym)m(b)s(olic)f(mnemonics)f(\(de\014ned)h (in)g(the)h(\014le)f(\014tsio.h\))h(rather)f(than)h(the)g(actual)g(in)m (teger)h(status)0 2406 y(v)-5 b(alues)30 b(to)h(impro)m(v)m(e)f(the)h (readabilit)m(y)d(of)j(their)e(co)s(de.)48 2665 y Fe(Symbolic)45 b(Const)190 b(Value)237 b(Meaning)48 2778 y(--------------)187 b(-----)94 b(------------------------)o(----)o(---)o(----)o(----)o(--) 1002 2891 y(0)191 b(OK,)47 b(no)g(error)48 3004 y(SAME_FILE)427 b(101)190 b(input)46 b(and)h(output)f(files)h(are)g(the)f(same)48 3117 y(TOO_MANY_FILES)187 b(103)j(tried)46 b(to)h(open)g(too)g(many)g (FITS)f(files)h(at)g(once)48 3230 y(FILE_NOT_OPENED)139 b(104)190 b(could)46 b(not)h(open)g(the)g(named)f(file)48 3343 y(FILE_NOT_CREATED)91 b(105)190 b(could)46 b(not)h(create)f(the)h (named)g(file)48 3456 y(WRITE_ERROR)331 b(106)190 b(error)46 b(writing)g(to)h(FITS)g(file)48 3569 y(END_OF_FILE)331 b(107)190 b(tried)46 b(to)h(move)g(past)g(end)g(of)g(file)48 3681 y(READ_ERROR)379 b(108)190 b(error)46 b(reading)g(from)h(FITS)f (file)48 3794 y(FILE_NOT_CLOSED)139 b(110)190 b(could)46 b(not)h(close)g(the)f(file)48 3907 y(ARRAY_TOO_BIG)235 b(111)190 b(array)46 b(dimensions)f(exceed)h(internal)g(limit)48 4020 y(READONLY_FILE)235 b(112)190 b(Cannot)46 b(write)g(to)i(readonly) d(file)48 4133 y(MEMORY_ALLOCATION)e(113)190 b(Could)46 b(not)h(allocate)f(memory)48 4246 y(BAD_FILEPTR)331 b(114)190 b(invalid)46 b(fitsfile)f(pointer)48 4359 y(NULL_INPUT_PTR)187 b(115)j(NULL)47 b(input)f(pointer)g(to)h(routine)48 4472 y(SEEK_ERROR)379 b(116)190 b(error)46 b(seeking)g(position)g(in)h(file) 48 4698 y(BAD_URL_PREFIX)235 b(121)142 b(invalid)46 b(URL)h(prefix)f (on)h(file)g(name)48 4811 y(TOO_MANY_DRIVERS)139 b(122)j(tried)46 b(to)h(register)f(too)h(many)g(IO)g(drivers)48 4924 y (DRIVER_INIT_FAILED)c(123)142 b(driver)46 b(initialization)e(failed)48 5036 y(NO_MATCHING_DRIVER)f(124)142 b(matching)45 b(driver)i(is)g(not)g (registered)48 5149 y(URL_PARSE_ERROR)187 b(125)142 b(failed)46 b(to)h(parse)g(input)f(file)h(URL)48 5262 y(RANGE_PARSE_ERROR)91 b(126)142 b(parse)46 b(error)h(in)g(range)f(list)48 5488 y(SHARED_BADARG)235 b(151)190 b(bad)47 b(argument)e(in)j(shared)e (memory)g(driver)48 5601 y(SHARED_NULPTR)235 b(152)190 b(null)47 b(pointer)e(passed)h(as)i(an)f(argument)48 5714 y(SHARED_TABFULL)187 b(153)j(no)47 b(more)g(free)f(shared)g (memory)h(handles)1882 5942 y Fj(157)p eop %%Page: 158 166 158 165 bop 0 299 a Fj(158)1589 b Fh(APPENDIX)31 b(C.)61 b(CFITSIO)29 b(ERR)m(OR)h(ST)-8 b(A)g(TUS)30 b(CODES)48 555 y Fe(SHARED_NOTINIT)187 b(154)j(shared)46 b(memory)g(driver)g(is)h (not)g(initialized)48 668 y(SHARED_IPCERR)235 b(155)190 b(IPC)47 b(error)f(returned)g(by)h(a)g(system)f(call)48 781 y(SHARED_NOMEM)283 b(156)190 b(no)47 b(memory)f(in)h(shared)f (memory)h(driver)48 894 y(SHARED_AGAIN)283 b(157)190 b(resource)45 b(deadlock)h(would)g(occur)48 1007 y(SHARED_NOFILE)235 b(158)190 b(attempt)46 b(to)h(open/create)e(lock)h(file)h(failed)48 1120 y(SHARED_NORESIZE)139 b(159)190 b(shared)46 b(memory)g(block)g (cannot)h(be)g(resized)f(at)h(the)g(moment)48 1346 y(HEADER_NOT_EMPTY) 91 b(201)190 b(header)46 b(already)g(contains)f(keywords)48 1458 y(KEY_NO_EXIST)283 b(202)190 b(keyword)46 b(not)h(found)f(in)h (header)48 1571 y(KEY_OUT_BOUNDS)187 b(203)j(keyword)46 b(record)g(number)g(is)h(out)g(of)g(bounds)48 1684 y(VALUE_UNDEFINED) 139 b(204)190 b(keyword)46 b(value)g(field)g(is)i(blank)48 1797 y(NO_QUOTE)475 b(205)190 b(string)46 b(is)h(missing)f(the)h (closing)f(quote)48 1910 y(BAD_KEYCHAR)331 b(207)190 b(illegal)46 b(character)f(in)i(keyword)f(name)h(or)g(card)48 2023 y(BAD_ORDER)427 b(208)190 b(required)45 b(keywords)h(out)h(of)g (order)48 2136 y(NOT_POS_INT)331 b(209)190 b(keyword)46 b(value)g(is)h(not)g(a)h(positive)d(integer)48 2249 y(NO_END)571 b(210)190 b(couldn't)45 b(find)i(END)g(keyword)48 2362 y(BAD_BITPIX)379 b(211)190 b(illegal)46 b(BITPIX)g(keyword)g(value)48 2475 y(BAD_NAXIS)427 b(212)190 b(illegal)46 b(NAXIS)g(keyword)g(value) 48 2588 y(BAD_NAXES)427 b(213)190 b(illegal)46 b(NAXISn)g(keyword)g (value)48 2700 y(BAD_PCOUNT)379 b(214)190 b(illegal)46 b(PCOUNT)g(keyword)g(value)48 2813 y(BAD_GCOUNT)379 b(215)190 b(illegal)46 b(GCOUNT)g(keyword)g(value)48 2926 y(BAD_TFIELDS)331 b(216)190 b(illegal)46 b(TFIELDS)g(keyword)f(value)48 3039 y(NEG_WIDTH)427 b(217)190 b(negative)45 b(table)i(row)g(size)48 3152 y(NEG_ROWS)475 b(218)190 b(negative)45 b(number)i(of)g(rows)f(in)i (table)48 3265 y(COL_NOT_FOUND)235 b(219)190 b(column)46 b(with)h(this)f(name)h(not)g(found)f(in)h(table)48 3378 y(BAD_SIMPLE)379 b(220)190 b(illegal)46 b(value)g(of)h(SIMPLE)f (keyword)48 3491 y(NO_SIMPLE)427 b(221)190 b(Primary)46 b(array)g(doesn't)g(start)g(with)h(SIMPLE)48 3604 y(NO_BITPIX)427 b(222)190 b(Second)46 b(keyword)g(not)h(BITPIX)48 3717 y(NO_NAXIS)475 b(223)190 b(Third)46 b(keyword)g(not)h(NAXIS)48 3830 y(NO_NAXES)475 b(224)190 b(Couldn't)45 b(find)i(all)g(the)g (NAXISn)f(keywords)48 3942 y(NO_XTENSION)331 b(225)190 b(HDU)47 b(doesn't)f(start)g(with)h(XTENSION)e(keyword)48 4055 y(NOT_ATABLE)379 b(226)190 b(the)47 b(CHDU)f(is)i(not)f(an)g (ASCII)f(table)g(extension)48 4168 y(NOT_BTABLE)379 b(227)190 b(the)47 b(CHDU)f(is)i(not)f(a)g(binary)f(table)g(extension)48 4281 y(NO_PCOUNT)427 b(228)190 b(couldn't)45 b(find)i(PCOUNT)f(keyword) 48 4394 y(NO_GCOUNT)427 b(229)190 b(couldn't)45 b(find)i(GCOUNT)f (keyword)48 4507 y(NO_TFIELDS)379 b(230)190 b(couldn't)45 b(find)i(TFIELDS)f(keyword)48 4620 y(NO_TBCOL)475 b(231)190 b(couldn't)45 b(find)i(TBCOLn)f(keyword)48 4733 y(NO_TFORM)475 b(232)190 b(couldn't)45 b(find)i(TFORMn)f(keyword)48 4846 y(NOT_IMAGE)427 b(233)190 b(the)47 b(CHDU)f(is)i(not)f(an)g(IMAGE) f(extension)48 4959 y(BAD_TBCOL)427 b(234)190 b(TBCOLn)46 b(keyword)g(value)g(<)i(0)f(or)g(>)h(rowlength)48 5072 y(NOT_TABLE)427 b(235)190 b(the)47 b(CHDU)f(is)i(not)f(a)g(table)48 5185 y(COL_TOO_WIDE)283 b(236)190 b(column)46 b(is)h(too)g(wide)g(to)g (fit)g(in)g(table)48 5297 y(COL_NOT_UNIQUE)187 b(237)j(more)47 b(than)f(1)i(column)e(name)g(matches)g(template)48 5410 y(BAD_ROW_WIDTH)235 b(241)190 b(sum)47 b(of)g(column)f(widths)g(not)h (=)h(NAXIS1)48 5523 y(UNKNOWN_EXT)331 b(251)190 b(unrecognizable)44 b(FITS)i(extension)g(type)48 5636 y(UNKNOWN_REC)331 b(252)190 b(unknown)46 b(record;)g(1st)g(keyword)g(not)h(SIMPLE)f(or)h(XTENSION)p eop %%Page: 159 167 159 166 bop 3764 299 a Fj(159)48 555 y Fe(END_JUNK)475 b(253)190 b(END)47 b(keyword)f(is)h(not)g(blank)48 668 y(BAD_HEADER_FILL)139 b(254)190 b(Header)46 b(fill)h(area)f(contains)g (non-blank)f(chars)48 781 y(BAD_DATA_FILL)235 b(255)190 b(Illegal)46 b(data)g(fill)h(bytes)f(\(not)h(zero)g(or)g(blank\))48 894 y(BAD_TFORM)427 b(261)190 b(illegal)46 b(TFORM)g(format)g(code)48 1007 y(BAD_TFORM_DTYPE)139 b(262)190 b(unrecognizable)44 b(TFORM)i(data)h(type)f(code)48 1120 y(BAD_TDIM)475 b(263)190 b(illegal)46 b(TDIMn)g(keyword)g(value)48 1233 y(BAD_HEAP_PTR)283 b(264)190 b(invalid)46 b(BINTABLE)f(heap)i(pointer)f(is)h(out)g(of)g (range)48 1458 y(BAD_HDU_NUM)331 b(301)190 b(HDU)47 b(number)f(<)h(1)48 1571 y(BAD_COL_NUM)331 b(302)190 b(column)46 b(number)g(<)i(1)f(or)g(>) h(tfields)48 1684 y(NEG_FILE_POS)283 b(304)190 b(tried)46 b(to)h(move)g(to)g(negative)f(byte)g(location)g(in)h(file)48 1797 y(NEG_BYTES)427 b(306)190 b(tried)46 b(to)h(read)g(or)g(write)g (negative)e(number)h(of)h(bytes)48 1910 y(BAD_ROW_NUM)331 b(307)190 b(illegal)46 b(starting)f(row)i(number)f(in)h(table)48 2023 y(BAD_ELEM_NUM)283 b(308)190 b(illegal)46 b(starting)f(element)h (number)g(in)h(vector)48 2136 y(NOT_ASCII_COL)235 b(309)190 b(this)47 b(is)g(not)g(an)g(ASCII)f(string)g(column)48 2249 y(NOT_LOGICAL_COL)139 b(310)190 b(this)47 b(is)g(not)g(a)g (logical)f(data)h(type)f(column)48 2362 y(BAD_ATABLE_FORMAT)d(311)190 b(ASCII)46 b(table)h(column)f(has)h(wrong)f(format)48 2475 y(BAD_BTABLE_FORMAT)d(312)190 b(Binary)46 b(table)g(column)g(has)h (wrong)g(format)48 2588 y(NO_NULL)523 b(314)190 b(null)47 b(value)f(has)h(not)g(been)f(defined)48 2700 y(NOT_VARI_LEN)283 b(317)190 b(this)47 b(is)g(not)g(a)g(variable)f(length)g(column)48 2813 y(BAD_DIMEN)427 b(320)190 b(illegal)46 b(number)g(of)h(dimensions) e(in)i(array)48 2926 y(BAD_PIX_NUM)331 b(321)190 b(first)46 b(pixel)h(number)f(greater)g(than)g(last)h(pixel)48 3039 y(ZERO_SCALE)379 b(322)190 b(illegal)46 b(BSCALE)g(or)h(TSCALn)f (keyword)g(=)h(0)48 3152 y(NEG_AXIS)475 b(323)190 b(illegal)46 b(axis)g(length)g(<)i(1)48 3378 y(NOT_GROUP_TABLE)330 b(340)142 b(Grouping)46 b(function)f(error)48 3491 y (HDU_ALREADY_MEMBER)186 b(341)48 3604 y(MEMBER_NOT_FOUND)282 b(342)48 3717 y(GROUP_NOT_FOUND)330 b(343)48 3830 y(BAD_GROUP_ID)474 b(344)48 3942 y(TOO_MANY_HDUS_TRACKED)42 b(345)48 4055 y(HDU_ALREADY_TRACKED)138 b(346)48 4168 y(BAD_OPTION)570 b(347)48 4281 y(IDENTICAL_POINTERS)186 b(348)48 4394 y(BAD_GROUP_ATTACH)282 b(349)48 4507 y(BAD_GROUP_DETACH)g(350)48 4733 y(NGP_NO_MEMORY)426 b(360)238 b(malloc)46 b(failed)48 4846 y(NGP_READ_ERR)474 b(361)238 b(read)46 b(error)h(from)f(file)48 4959 y(NGP_NUL_PTR)522 b(362)238 b(null)46 b(pointer)g(passed)g(as)h (an)g(argument.)1575 5072 y(Passing)f(null)g(pointer)g(as)h(a)h(name)f (of)1575 5185 y(template)f(file)g(raises)g(this)h(error)48 5297 y(NGP_EMPTY_CURLINE)234 b(363)k(line)46 b(read)h(seems)f(to)h(be)h (empty)e(\(used)1575 5410 y(internally\))48 5523 y (NGP_UNREAD_QUEUE_FULL)c(364)238 b(cannot)46 b(unread)g(more)g(then)h (1)g(line)g(\(or)g(single)1575 5636 y(line)g(twice\))p eop %%Page: 160 168 160 167 bop 0 299 a Fj(160)1589 b Fh(APPENDIX)31 b(C.)61 b(CFITSIO)29 b(ERR)m(OR)h(ST)-8 b(A)g(TUS)30 b(CODES)48 555 y Fe(NGP_INC_NESTING)330 b(365)238 b(too)46 b(deep)h(include)f (file)h(nesting)e(\(infinite)1575 668 y(loop,)h(template)g(includes)f (itself)i(?\))48 781 y(NGP_ERR_FOPEN)426 b(366)238 b(fopen\(\))45 b(failed,)h(cannot)g(open)h(template)e(file)48 894 y(NGP_EOF)714 b(367)238 b(end)46 b(of)i(file)e(encountered)f(and)i(not)g(expected)48 1007 y(NGP_BAD_ARG)522 b(368)238 b(bad)46 b(arguments)g(passed.)g (Usually)f(means)1575 1120 y(internal)h(parser)g(error.)g(Should)g(not) h(happen)48 1233 y(NGP_TOKEN_NOT_EXPECT)90 b(369)238 b(token)46 b(not)h(expected)e(here)48 1458 y(BAD_I2C)523 b(401)190 b(bad)47 b(int)g(to)g(formatted)e(string)h(conversion)48 1571 y(BAD_F2C)523 b(402)190 b(bad)47 b(float)f(to)h(formatted)f (string)g(conversion)48 1684 y(BAD_INTKEY)379 b(403)190 b(can't)46 b(interpret)g(keyword)f(value)i(as)g(integer)48 1797 y(BAD_LOGICALKEY)187 b(404)j(can't)46 b(interpret)g(keyword)f (value)i(as)g(logical)48 1910 y(BAD_FLOATKEY)283 b(405)190 b(can't)46 b(interpret)g(keyword)f(value)i(as)g(float)48 2023 y(BAD_DOUBLEKEY)235 b(406)190 b(can't)46 b(interpret)g(keyword)f (value)i(as)g(double)48 2136 y(BAD_C2I)523 b(407)190 b(bad)47 b(formatted)e(string)h(to)h(int)g(conversion)48 2249 y(BAD_C2F)523 b(408)190 b(bad)47 b(formatted)e(string)h(to)h (float)g(conversion)48 2362 y(BAD_C2D)523 b(409)190 b(bad)47 b(formatted)e(string)h(to)h(double)f(conversion)48 2475 y(BAD_DATATYPE)283 b(410)190 b(illegal)46 b(datatype)f(code)i(value)48 2588 y(BAD_DECIM)427 b(411)190 b(bad)47 b(number)f(of)h(decimal)f (places)g(specified)48 2700 y(NUM_OVERFLOW)283 b(412)190 b(overflow)45 b(during)i(data)f(type)h(conversion)48 2813 y(DATA_COMPRESSION_ERR)137 b(413)95 b(error)46 b(compressing)f (image)48 2926 y(DATA_DECOMPRESSION_ERR)c(414)95 b(error)46 b(uncompressing)f(image)48 3152 y(BAD_DATE)475 b(420)190 b(error)46 b(in)h(date)g(or)g(time)g(conversion)48 3378 y(PARSE_SYNTAX_ERR)91 b(431)190 b(syntax)46 b(error)g(in)i(parser)e (expression)48 3491 y(PARSE_BAD_TYPE)187 b(432)j(expression)45 b(did)i(not)g(evaluate)e(to)i(desired)f(type)48 3604 y(PARSE_LRG_VECTOR)91 b(433)190 b(vector)46 b(result)g(too)h(large)f (to)i(return)e(in)h(array)48 3717 y(PARSE_NO_OUTPUT)139 b(434)190 b(data)47 b(parser)f(failed)g(not)h(sent)f(an)h(out)g(column) 48 3830 y(PARSE_BAD_COL)235 b(435)190 b(bad)47 b(data)f(encounter)g (while)g(parsing)g(column)48 3942 y(PARSE_BAD_OUTPUT)91 b(436)190 b(Output)46 b(file)h(not)g(of)g(proper)f(type)48 4168 y(ANGLE_TOO_BIG)235 b(501)190 b(celestial)45 b(angle)i(too)f (large)h(for)g(projection)48 4281 y(BAD_WCS_VAL)331 b(502)190 b(bad)47 b(celestial)e(coordinate)g(or)i(pixel)g(value)48 4394 y(WCS_ERROR)427 b(503)190 b(error)46 b(in)h(celestial)f (coordinate)f(calculation)48 4507 y(BAD_WCS_PROJ)283 b(504)190 b(unsupported)45 b(type)h(of)h(celestial)f(projection)48 4620 y(NO_WCS_KEY)379 b(505)190 b(celestial)45 b(coordinate)g(keywords) h(not)h(found)48 4733 y(APPROX_WCS_KEY)187 b(506)j(approximate)45 b(wcs)i(keyword)e(values)h(were)h(returned)p eop %%Trailer end userdict /end-hook known{end-hook}if %%EOF