InterBase 5 Server

API Guide

InterBase
SOFTWARE CORPORATION
®

1800 Green Hills Road Scotts Valley, CA 95066 http://www.interbase.com

February 27, 1998 (D:\5.1\5APIGuide\ApiTitle.fm5)

InterBase Software Corp. and Borland International may have patents and/or pending patent applications covering
subject matter in this document. The furnishing of this document does not convey any license to these patents.
Copyright 1998 InterBase Software Corporation. All rights reserved. All InterBase products are trademarks or
registered trademarks of InterBase Software Corporation. All Borland products are trademarks or registered
trademarks of Borland International, Inc. Other brand and product names are trademarks or registered trademarks
of their respective holders.
INT0050WW21003 5E3R0298
9899000102-9 8 7 6 5 4 3 2 1
D4
Table of Contents

/LVWRI7DEOHV                    L[ 6SHFLI\LQJXVHUQDPHDQGSDVVZRUG        
8VLQJHQYLURQPHQWYDULDEOHV            
Chapter 1 Using the API Guide 6HWWLQJDGHIDXOWGDWDEDVHGLUHFWRU\       
:KRVKRXOGXVHWKLVJXLGH              6HWWLQJDXVHUQDPHDQGSDVVZRUG       
7RSLFVFRYHUHGLQWKLVJXLGH              'DWDW\SHV                      
6DPSOHGDWDEDVHDQGDSSOLFDWLRQV           &DOOLQJFRQYHQWLRQV                
%XLOGLQJDSSOLFDWLRQV                
3DUW, $3,8VHU·V*XLGH
&RPSLOHUV                    
Chapter 2 Application Requirements /LQNLQJ                      
5HTXLUHPHQWVIRUDOODSSOLFDWLRQV           ,QFOXGHILOHV                   
,QFOXGLQJLEDVHK                  8VLQJ0LFURVRIW&              
'DWDEDVHUHTXLUHPHQWV               8VLQJ%RUODQG&&             
'HFODULQJGDWDEDVHKDQGOHV           8VLQJWKH%RUODQGLQWHJUDWHGGHYHORSPHQW
HQYLURQPHQW ,'(            
6HWWLQJXSD'3%               
,'(GHIDXOW                 
7UDQVDFWLRQUHTXLUHPHQWV             
,'(3URMHFW2SWLRQVGLDORJER[       
'HFODULQJWUDQVDFWLRQKDQGOHV         
0RGXOHGHILQLWLRQILOH              
6HWWLQJXSD73%               
8VLQJG\QDPLFOLQNOLEUDULHV '//V       
$GGLWLRQDOUHTXLUHPHQWV              
([DPSOHSURJUDPV               
0LFURVRIW:LQGRZVUHTXLUHPHQWV       
'64/UHTXLUHPHQWV               Chapter 4 Working with Databases
%OREUHTXLUHPHQWV                &RQQHFWLQJWRGDWDEDVHV              
$UUD\UHTXLUHPHQWV                &UHDWLQJGDWDEDVHKDQGOHV            
(YHQWUHTXLUHPHQWV                'HFODULQJGDWDEDVHKDQGOHV         
(UURUKDQGOLQJUHTXLUHPHQWV           ,QLWLDOL]LQJGDWDEDVHKDQGOHV         
&RPSLOLQJDQGOLQNLQJ                &UHDWLQJDQGSRSXODWLQJD'3%         
$GGLQJSDUDPHWHUVWRD'3%          
Chapter 3 Programming with
the InterBase API $WWDFKLQJWRDGDWDEDVH             
%DVLFSURFHGXUHIRUDSSOLFDWLRQGHYHORSPHQW   5HTXHVWLQJLQIRUPDWLRQDERXWDQDWWDFKPHQW   
6XSSRUWHGGHYHORSPHQWHQYLURQPHQWV       5HTXHVWLQJEXIIHULWHPVDQGUHVXOW
EXIIHUYDOXHV               
8VHUQDPHDQGSDVVZRUGUHTXLUHPHQWV      

API GUIDE iii

 'DWDEDVHFKDUDFWHULVWLFV            3URFHVVLQJDUUD\GDWD              
(QYLURQPHQWDOFKDUDFWHULVWLFV         :ULWLQJDQ$3,DSSOLFDWLRQWRSURFHVV
3HUIRUPDQFHVWDWLVWLFV             64/VWDWHPHQWV               
'DWDEDVHRSHUDWLRQFRXQWV          'HWHUPLQLQJLI$3,FDOOVFDQSURFHVVDQ
64/VWDWHPHQW              
LVFBGDWDEDVHBLQIR FDOOH[DPSOH        
5HSUHVHQWLQJDQ64/VWDWHPHQWDVD
'LVFRQQHFWLQJIURPGDWDEDVHV          
FKDUDFWHUVWULQJ              
'HOHWLQJDGDWDEDVH                
6SHFLI\LQJSDUDPHWHUVLQ64/
VWDWHPHQWVWULQJV             
Chapter 5 Working with Transactions
8QGHUVWDQGLQJWKH;64/'$           
6WDUWLQJWUDQVDFWLRQV                
;64/'$ILHOGGHVFULSWLRQV           
&UHDWLQJWUDQVDFWLRQKDQGOHV          
,QSXWGHVFULSWRUV                
'HFODULQJWUDQVDFWLRQKDQGOHV        
2XWSXWGHVFULSWRUV               
,QLWLDOL]LQJWUDQVDFWLRQKDQGOHV       
8VLQJWKH;64/'$B/(1*7+PDFUR    
&UHDWLQJDWUDQVDFWLRQSDUDPHWHUEXIIHU    
64/GDWDW\SHPDFURFRQVWDQWV         
6SHFLI\LQJWKHWUDQVDFWLRQYHUVLRQQXPEHU 
+DQGOLQJYDU\LQJVWULQJGDWDW\SHV        
6SHFLI\LQJDFFHVVPRGH           
+DQGOLQJ180(5,&DQG'(&,0$/
6SHFLI\LQJLVRODWLRQOHYHO           GDWDW\SHV                 
6SHFLI\LQJORFNUHVROXWLRQ           &RHUFLQJGDWDW\SHV               
6SHFLI\LQJWDEOHUHVHUYDWLRQ          &RHUFLQJFKDUDFWHUGDWDW\SHV         
8VLQJWKHGHIDXOW73%             &RHUFLQJQXPHULFGDWDW\SHV         
&DOOLQJLVFBVWDUWBWUDQVDFWLRQ           6HWWLQJD18//LQGLFDWRU          
&DOOLQJLVFBVWDUWBPXOWLSOH             $OLJQLQJQXPHULFDOGDWD             
(QGLQJWUDQVDFWLRQV                 '64/SURJUDPPLQJPHWKRGV           
8VLQJLVFBFRPPLWBWUDQVDFWLRQ          0HWKRG1RQTXHU\VWDWHPHQWVZLWKRXW
8VLQJLVFBFRPPLWBUHWDLQLQJ         SDUDPHWHUV                
8VLQJLVFBSUHSDUHBWUDQVDFWLRQ        8VLQJLVFBGVTOBH[HFXWHBLPPHGLDWH     
8VLQJLVFBSUHSDUHBWUDQVDFWLRQ         8VLQJLVFBGVTOBSUHSDUH  DQG
8VLQJLVFBUROOEDFNBWUDQVDFWLRQ          LVFBGVTOBH[HFXWH            
0HWKRG1RQTXHU\VWDWHPHQWV
Chapter 6 Working with Dynamic SQL ZLWKSDUDPHWHUV              
2YHUYLHZRIWKH'64/SURJUDPPLQJSURFHVV   &UHDWLQJWKHLQSXW;64/'$        
'64/$3,OLPLWDWLRQV                3UHSDULQJDQGH[HFXWLQJDVWDWHPHQWVWULQJ
ZLWKSDUDPHWHUV            
$FFHVVLQJGDWDEDVHV               
5HH[HFXWLQJWKHVWDWHPHQWVWULQJ      
+DQGOLQJWUDQVDFWLRQV              
&UHDWLQJDGDWDEDVH                0HWKRG4XHU\VWDWHPHQWVZLWKRXW
SDUDPHWHUV                
3URFHVVLQJ%OREGDWD              

iv INTERBASE 5
 3UHSDULQJWKHRXWSXW;64/'$        $VVRFLDWLQJWKHQHZ%OREZLWKWKH
3UHSDULQJDTXHU\VWDWHPHQWVWULQJ %OREFROXPQ              
ZLWKRXWSDUDPHWHUV           'HOHWLQJD%ORE                
([HFXWLQJDVWDWHPHQWVWULQJZLWKLQ 5HTXHVWLQJLQIRUPDWLRQDERXWDQRSHQ%ORE   
WKHFRQWH[WRIDFXUVRU         ,WHPOLVWEXIIHULWHPVDQGUHVXOWEXIIHUYDOXHV
5HH[HFXWLQJDTXHU\VWDWHPHQWVWULQJ LVFBEOREBLQIR  FDOOH[DPSOH         
ZLWKRXWSDUDPHWHUV          
%OREGHVFULSWRUV                  
0HWKRG4XHU\VWDWHPHQWVZLWKSDUDPHWHUV 
3RSXODWLQJD%OREGHVFULSWRU            
3UHSDULQJWKHLQSXW;64/'$       
)LOWHULQJ%OREGDWD                 
3UHSDULQJWKHRXWSXW;64/'$       
8VLQJ\RXURZQILOWHUV             
3UHSDULQJDTXHU\VWDWHPHQWVWULQJ
'HFODULQJDQH[WHUQDO%OREILOWHU
ZLWK SDUDPHWHUV            
WRWKHGDWDEDVH             
([HFXWLQJDTXHU\VWDWHPHQWVWULQJ
:ULWLQJDQH[WHUQDO%OREILOWHU         
ZLWKLQWKHFRQWH[WRIDFXUVRU    
'HILQLQJWKHILOWHUIXQFWLRQ         
5HH[HFXWLQJDTXHU\VWDWHPHQWVWULQJ
ZLWK SDUDPHWHUV             'HILQLQJWKH%OREFRQWUROVWUXFWXUH     
'HWHUPLQLQJDQXQNQRZQVWDWHPHQWW\SH 3URJUDPPLQJILOWHUIXQFWLRQDFWLRQV     
DWUXQWLPH                   :ULWLQJDQDSSOLFDWLRQWKDWUHTXHVWVILOWHULQJ 
8QGHUVWDQGLQJWKH%ORESDUDPHWHUEXIIHU  
Chapter 7 Working with Blob Data
5HTXHVWLQJILOWHUXVDJH            
:KDWLVD%ORE"                  
+RZDUH%OREGDWDVWRUHG"            Chapter 8 Working with Array Data
%OREVXEW\SHV                   ,QWURGXFWLRQWRDUUD\V               
%OREGDWDEDVHVWRUDJH              $UUD\GDWDEDVHVWRUDJH            
%OREGDWDRSHUDWLRQV                 $UUD\GHVFULSWRUV               
5HDGLQJGDWDIURPD%ORE            3RSXODWLQJDQDUUD\GHVFULSWRU        
&UHDWLQJWKH6(/(&7VWDWHPHQW       $FFHVVLQJDUUD\GDWD                
3UHSDULQJWKHRXWSXW;64/'$        5HDGLQJGDWDIURPDQDUUD\          
3UHSDULQJWKH6(/(&7VWDWHPHQW &UHDWLQJWKH6(/(&7VWDWHPHQW      
IRUH[HFXWLRQ              3UHSDULQJWKHRXWSXW;64/'$       
([HFXWLQJWKHVWDWHPHQW            3UHSDULQJWKH6(/(&7VWDWHPHQW
)HWFKLQJVHOHFWHGURZV             IRUH[HFXWLRQ              
5HDGLQJDQGSURFHVVLQJWKH%OREGDWD    ([HFXWLQJWKHVWDWHPHQW           
:ULWLQJGDWDWRD%ORE             3RSXODWLQJWKHDUUD\GHVFULSWRU       
3UHSDULQJWKH83'$7(RU,16(57 )HWFKLQJVHOHFWHGURZV            
VWDWHPHQW                5HDGLQJDQGSURFHVVLQJWKHDUUD\GDWD    
&UHDWLQJDQHZ%OREDQGVWRULQJGDWD     :ULWLQJGDWDWRDQDUUD\            

API GUIDE v
 3UHSDULQJWKHDUUD\GHVFULSWRU         &UHDWLQJ(3%VZLWKLVFBHYHQWBEORFN       
3UHSDULQJWKHDUUD\EXIIHUZLWKGDWD     :DLWLQJRQHYHQWVZLWKLVFBZDLWBIRUBHYHQW     
3UHSDULQJWKH83'$7(RU,16(57 &RQWLQXRXVSURFHVVLQJZLWKLVFBTXHBHYHQWV    
VWDWHPHQW                &UHDWLQJDQ$67                
&DOOLQJLVFBDUUD\BSXWBVOLFH          $FRPSOHWHLVFBTXHBHYHQWV  H[DPSOH    
$VVRFLDWLQJWKHQHZDUUD\ZLWKWKH 'HWHUPLQLQJZKLFKHYHQWVRFFXUUHGZLWK
DUUD\FROXPQ              LVFBHYHQWBFRXQWV               
'HOHWLQJDQDUUD\                &DQFHOLQJLQWHUHVWLQDV\QFKURQRXVHYHQWV
ZLWKLVFBFDQFHOBHYHQWV            
Chapter 9 Working with Conversions
&RQYHUWLQJGDWHVIURP,QWHU%DVHWR&IRUPDW   3DUW,, $3,5HIHUHQFH*XLGH
&RQYHUWLQJGDWHVIURP&WR,QWHU%DVHIRUPDW  
Chapter 12 API Function Reference
5HYHUVLQJE\WHRUGHURIQXPEHUVZLWK
LVFBYD[BLQWHJHU                 )XQFWLRQFDWHJRULHV                
$UUD\IXQFWLRQV                
Chapter 10 Handling Error Conditions %OREIXQFWLRQV                 
6HWWLQJXSDQHUURUVWDWXVYHFWRU          'DWDEDVHIXQFWLRQV              
8VLQJLQIRUPDWLRQLQWKHVWDWXVYHFWRU       &RQYHUVLRQIXQFWLRQV             
&KHFNLQJWKHVWDWXVYHFWRUIRUHUURUV      '64/IXQFWLRQV                
'LVSOD\LQJ,QWHU%DVHHUURUPHVVDJHV      (UURUKDQGOLQJIXQFWLRQV           
&DSWXULQJ,QWHU%DVHHUURUPHVVDJHV      (YHQWIXQFWLRQV                
6HWWLQJDQ64/&2'(YDOXHRQHUURU     ,QIRUPDWLRQIXQFWLRQV             
'LVSOD\LQJ64/HUURUPHVVDJHV        6HFXULW\IXQFWLRQV               
&DSWXULQJ64/HUURUPHVVDJHV         7UDQVDFWLRQFRQWUROIXQFWLRQV         
3DUVLQJWKHVWDWXVYHFWRU            8VLQJIXQFWLRQGHILQLWLRQV             
+RZWKHVWDWXVYHFWRULVSDUVHG        LVFBDGGBXVHU                 
0HDQLQJRIWKHILUVWORQJLQDFOXVWHU     LVFBDUUD\BJHWBVOLFH              
0HDQLQJRIWKHVHFRQGORQJLQDFOXVWHU   LVFBDUUD\BORRNXSBERXQGV          
0HDQLQJRIWKHWKLUGORQJLQDFOXVWHU     LVFBDUUD\BORRNXSBGHVF            
6WDWXVYHFWRUSDUVLQJH[DPSOH         LVFBDUUD\BSXWBVOLFH              
LVFBDUUD\BVHWBGHVF              
Chapter 11 Working with Events
LVFBDWWDFKBGDWDEDVH             
8QGHUVWDQGLQJWKHHYHQWPHFKDQLVP       
LVFBEOREBGHIDXOWBGHVF            
(YHQWSDUDPHWHUEXIIHUV           
LVFBEOREBJHQBESE              
6\QFKURQRXVHYHQWQRWLILFDWLRQ        
LVFBEOREBLQIR                 
$V\QFKURQRXVHYHQWQRWLILFDWLRQ       
LVFBEOREBORRNXSBGHVF            
7UDQVDFWLRQFRQWURORIHYHQWV         

vi INTERBASE 5
 LVFBEOREBVHWBGHVF               LVFBSUHSDUHBWUDQVDFWLRQ           
LVFBFDQFHOBEORE                LVFBSUHSDUHBWUDQVDFWLRQ           
LVFBFDQFHOBHYHQWV               LVFBSULQWBVTOHUURU              
LVFBFORVHBEORE                 LVFBSULQWBVWDWXV               
LVFBFRPPLWBUHWDLQLQJ             LVFBSXWBVHJPHQW               
LVFBFRPPLWBWUDQVDFWLRQ            LVFBTXHBHYHQWV                
LVFBFUHDWHBEORE                LVFBUROOEDFNBWUDQVDFWLRQ           
LVFBGDWDEDVHBLQIR               LVFBVTOFRGH                  
LVFBGHFRGHBGDWH                LVFBVTOBLQWHUSUHWH              
LVFBGHOHWHBXVHU                LVFBVWDUWBPXOWLSOH              
LVFBGHWDFKBGDWDEDVH              LVFBVWDUWBWUDQVDFWLRQ             
LVFBGURSBGDWDEDVH               LVFBWUDQVDFWLRQBLQIR             
LVFBGVTOBDOORFDWHBVWDWHPHQW          LVFBYD[BLQWHJHU                
LVFBGVTOBDOORFBVWDWHPHQW           LVFBYHUVLRQ                  
LVFBGVTOBGHVFULEH               LVFBZDLWBIRUBHYHQW              
LVFBGVTOBGHVFULEHBELQG           
Appendix A InterBase Document
LVFBGVTOBH[HFXWH               
Conventions
LVFBGVTOBH[HFXWH              
7KH,QWHU%DVHGRFXPHQWDWLRQVHW         
LVFBGVTOBH[HFXWHBLPPHGLDWH        
3ULQWLQJFRQYHQWLRQV                
LVFBGVTOBH[HFBLPPHG           
6\QWD[FRQYHQWLRQV                 
LVFBGVTOBIHWFK                
LVFBGVTOBIUHHBVWDWHPHQW            Appendix B Data Structures
'64/BFORVH                  $UUD\GHVFULSWRU                  
'64/BGURS                  'DWDW\SHVIRUDUUD\GHVFULSWRUV          
LVFBGVTOBSUHSDUH                %OREGHVFULSWRU                   
LVFBGVTOBVHWBFXUVRUBQDPH          &KDUDFWHUVHWV                 
LVFBGVTOBVTOBLQIR               %ORELQIRUPDWLRQEXIIHUV           
LVFBHQFRGHBGDWH                ,WHPOLVWEXIIHU                
LVFBHYHQWBEORFN                5HVXOWEXIIHU                 
LVFBHYHQWBFRXQWV               %OREEXIIHULWHPV               
LVFBH[SDQGBGSE                %ORESDUDPHWHUEXIIHU             
LVFBJHWBVHJPHQW                'DWDEDVHLQIRUPDWLRQUHTXHVWEXIIHUDQG
LVFBLQWHUSUHWH                 UHVXOWEXIIHU                 
LVFBPRGLI\BXVHU                5HTXHVWEXIIHU                 
LVFBRSHQBEORE                5HVXOWEXIIHU                  

API GUIDE vii

 5HTXHVWEXIIHULWHPVDQGUHVXOWEXIIHUYDOXHV 
'DWDEDVHFKDUDFWHULVWLFV           
(QYLURQPHQWDOFKDUDFWHULVWLFV        
3HUIRUPDQFHVWDWLVWLFV            
'DWDEDVHRSHUDWLRQFRXQWV         
64/GDWDW\SHPDFURFRQVWDQWV          
6WDWXVYHFWRU                    
0HDQLQJRIWKHILUVWORQJLQDFOXVWHU       
7UDQVDFWLRQSDUDPHWHUEXIIHU           
;64/'$DQG;64/9$5            
;64/'$ILHOGGHVFULSWLRQV         
;64/9$5ILHOGGHVFULSWLRQV         

viii INTERBASE 5
List of Tables

7DEOH $3,*XLGHFKDSWHUV                            

7DEOH (QYLURQPHQWYDULDEOHVXVHGE\,QWHU%DVH                 
7DEOH ,QWHU%DVHOLEUDU\ILOHQDPHV                        
7DEOH 0LFURVRIW&FRPSLOHURSWLRQV                       
7DEOH %RUODQG&FRPSLOHURSWLRQV                        
7DEOH $3,GDWDEDVHIXQFWLRQV                           
7DEOH '3%SDUDPHWHUV                               
7DEOH $OSKDEHWLFDOOLVWRI'3%SDUDPHWHUV                    
7DEOH '3%SDUDPHWHUVUHFRJQL]HGE\LVFBH[SDQGBGSE             
7DEOH LVFBH[SDQGBGES SDUDPHWHUV                       
7DEOH 'DWDEDVHLQIRUPDWLRQLWHPVIRUGDWDEDVHFKDUDFWHULVWLFV          
7DEOH 'DWDEDVHLQIRUPDWLRQLWHPVIRUHQYLURQPHQWDOFKDUDFWHULVWLFV       
7DEOH 'DWDEDVHLQIRUPDWLRQLWHPVIRUSHUIRUPDQFHVWDWLVWLFV           
7DEOH 'DWDEDVHLQIRUPDWLRQLWHPVIRURSHUDWLRQFRXQWV             
7DEOH $3,WUDQVDFWLRQIXQFWLRQV                         
7DEOH $GGLWLRQDO$3,WUDQVDFWLRQIXQFWLRQV                   
7DEOH 73%FRQVWDQWV                                
7DEOH ,VRODWLRQOHYHOLQWHUDFWLRQZLWKUHDGDQGZULWHRSHUDWLRQV         
7DEOH 64/VWDWHPHQWVWKDWFDQQRWEHSURFHVVHGE\WKH$3,           
7DEOH ;64/'$ILHOGGHVFULSWLRQV                         
7DEOH ;64/9$5ILHOGGHVFULSWLRQV                        
7DEOH 64/GDWDW\SHVPDFURH[SUHVVLRQVDQG&GDWDW\SHV            
7DEOH 64/VWDWHPHQWVWULQJVDQGUHFRPPHQGHGSURFHVVLQJPHWKRGV      
7DEOH 6WDWHPHQWW\SHV                               
7DEOH $3,%OREIXQFWLRQV                             
7DEOH %OREUHTXHVWDQGUHWXUQLWHPV                        
7DEOH 6WDWXVPHVVDJHUHWXUQLWHPV                         
7DEOH LVFBEOREBFWOVWUXFWXUHILHOGGHVFULSWLRQV                  
7DEOH $FWLRQFRQVWDQWV                               
7DEOH %ORESDUDPHWHUEXIIHUSDUDPHWHUW\SHV                   
7DEOH $3,DUUD\DFFHVVIXQFWLRQV                         
7DEOH (UURUKDQGOLQJIXQFWLRQV                          
7DEOH ,QWHUSUHWDWLRQRIVWDWXVYHFWRUFOXVWHUV                   

API GUIDE ix
7DEOH GHILQHVIRUVWDWXVYHFWRUQXPHULFGHVFULSWRUV               
7DEOH $3,HYHQWIXQFWLRQV                            
7DEOH $UUD\IXQFWLRQV                               
7DEOH %OREIXQFWLRQV                                
7DEOH 'DWDEDVHIXQFWLRQV                             
7DEOH 'DWHDQGFRQYHUVLRQIXQFWLRQV                       
7DEOH '64/IXQFWLRQV                               
7DEOH (UURUKDQGOLQJIXQFWLRQV                          
7DEOH (YHQWIXQFWLRQV                               
7DEOH ,QIRUPDWLRQIXQFWLRQV                            
7DEOH 6HFXULW\IXQFWLRQV                              
7DEOH 7UDQVDFWLRQFRQWUROIXQFWLRQV                        
7DEOH )XQFWLRQGHVFULSWLRQIRUPDW                        
7DEOH (UURUPHVVDJHVIRUXVHUVHFXULW\IXQFWLRQV                
7DEOH 'DWDW\SHVIRUDUUD\GHVFULSWRUILHOGV                    
7DEOH 'DWDW\SHVIRUDUUD\GHVFULSWRUILHOGV                    
7DEOH 'DWDW\SHVIRUDUUD\GHVFULSWRUILHOGV                    
7DEOH %OREGHVFULSWRUILHOGV                            
7DEOH %OREGHVFULSWRUILHOGV                            
7DEOH (UURUPHVVDJHVIRUXVHUVHFXULW\IXQFWLRQV                
7DEOH (UURUPHVVDJHVIRUXVHUVHFXULW\IXQFWLRQV                
7DEOH 7UDQVDFWLRQLQIRUPDWLRQUHTXHVWLWHP                   
7DEOH 6WDWXVPHVVDJHUHWXUQLWHPV                        
7DEOH$ %RRNVLQWKH,QWHU%DVHGRFXPHQWDWLRQVHW              
7DEOH$ 7H[WFRQYHQWLRQV                              
7DEOH$ 6\QWD[FRQYHQWLRQV                             
7DEOH% $UUD\GHVFULSWRUILHOGV                           
7DEOH% 'DWDW\SHVIRUDUUD\GHVFULSWRUV                       
7DEOH% %OREGHVFULSWRUILHOGV                           
7DEOH% %ORELQIRUPDWLRQLWHPVDQGUHWXUQYDOXHV                 
7DEOH% 6WDWXVPHVVDJHUHWXUQLWHPV                        
7DEOH% %ORESDUDPHWHUEXIIHUSDUDPHWHUW\SHV                  
7DEOH% 6WDWXVPHVVDJHUHWXUQLWHPV                        
7DEOH% 'DWDEDVHLQIRUPDWLRQLWHPVIRUGDWDEDVHFKDUDFWHULVWLFV          
7DEOH% 'DWDEDVHLQIRUPDWLRQLWHPVIRUHQYLURQPHQWDOFKDUDFWHULVWLFV       
7DEOH% 'DWDEDVHLQIRUPDWLRQLWHPVIRUSHUIRUPDQFHVWDWLVWLFV           

x INTERBASE 5
7DEOH% 'DWDEDVHLQIRUPDWLRQLWHPVIRURSHUDWLRQFRXQWV             
7DEOH% '3%SDUDPHWHUV                              
7DEOH% $OSKDEHWLFDOOLVWRI'3%SDUDPHWHUV                    
7DEOH% 64/GDWDW\SHVPDFURH[SUHVVLRQVDQG&GDWDW\SHV           
7DEOH% ,QWHUSUHWDWLRQRIVWDWXVYHFWRUFOXVWHUV                  
7DEOH% GHILQHVIRUVWDWXVYHFWRUQXPHULFGHVFULSWRUV             
7DEOH% 73%FRQVWDQWV                               
7DEOH% ;64/'$ILHOGGHVFULSWLRQV                        
7DEOH% ;64/9$5ILHOGGHVFULSWLRQV                       

API GUIDE xi
 CHAPTER

Using the API Guide

Chapter1
1
7KH,QWHU%DVH$3,*XLGHLVDWDVNRULHQWHGH[SODQDWLRQRIKRZWRZULWHSUHSURFHVVFRPSLOH
DQGOLQNGDWDEDVHDSSOLFDWLRQVXVLQJWKH,QWHU%DVH$SSOLFDWLRQV3URJUDPPLQJ,QWHUIDFH
$3, DQGDKRVWSURJUDPPLQJODQJXDJHHLWKHU&RU&
7KLVFKDSWHUGHVFULEHVZKRVKRXOGUHDGWKLVERRNDQGSURYLGHVDEULHIRYHUYLHZ
RILWVFKDSWHUV

Who should use this guide

7KH,QWHU%DVH$3,*XLGHLVLQWHQGHGIRUNQRZOHGJHDEOHGDWDEDVHDSSOLFDWLRQVSURJUDPPHUV
,WDVVXPHVIXOONQRZOHGJHRI
g 64/DQGG\QDPLF64/ '64/ 
g 5HODWLRQDOGDWDEDVHSURJUDPPLQJ
g &SURJUDPPLQJ

1
 CHAPTER 1 USING THE API GUIDE

Topics covered in this guide

7KH$3,*XLGHLVGLYLGHGLQWRWZRSDUWV
g $WDVNRULHQWHGXVHU·VJXLGHWKDWH[SODLQVKRZWRXVH$3,IXQFWLRQFDOOVWRSHUIRUPUHODWHG
GDWDEDVHWDVNVVXFKDVDWWDFKLQJWRDQGGHWDFKLQJIURPDGDWDEDVH
g $Q$3,IXQFWLRQFDOOUHIHUHQFHWKDWGHVFULEHVWKHSXUSRVHRIHDFKIXQFWLRQLWVV\QWD[LWV
SDUDPHWHUVUHTXLUHPHQWVUHVWULFWLRQVDQGUHWXUQYDOXHVDVZHOODVH[DPSOHVRIXVHDQG
FURVVUHIHUHQFHVWRUHODWHGIXQFWLRQV
7KHIROORZLQJWDEOHOLVWVWKHWDVNRULHQWHGFKDSWHUVLQWKH$3,*XLGHDQGSURYLGHVDEULHI
GHVFULSWLRQRIWKHP

Chapter Description
Chapter 2, “Application Requirements” Describes support structures and elements common to programming with
API calls
Chapter 3, “Programming with the InterBase API” Describes special requirements for programming InterBase applications
with the InterBase API
Chapter 4, “Working with Databases” Describes how to attach to and detach from databases, and how to request
information about attachments
Chapter 5, “Working with Transactions” Explains how to start transactions in different modes, and how to commit
them or roll them back
Chapter 6, “Working with Dynamic SQL” Describes how to process DSQL data definition and data manipulation
statements using API calls
Chapter 7, “Working with Blob Data” Describes how to select, insert, update, and delete Blob data in applications
Chapter 8, “Working with Array Data” Describes how to select, insert, update, and delete array data in applications
Chapter 9, “Working with Conversions” Describes how to select, insert, update, and delete DATE data in
applications, and how to reverse the byte order of numbers with
isc_vax_integer()
Chapter 10, “Handling Error Conditions” Describes how to trap and handle database errors in applications
Chapter 11, “Working with Events” Explains how triggers interact with applications and describes how to
register interest in events, wait on them, and respond to them in
applications
TABLE 1.1 API Guide chapters

2 INTERBASE 5
SAMPLE DATABASE AND APPLICATIONS

Chapter Description
Chapter 12, “API Function Reference” Describes the syntax of each function call in detail.
Appendix A, “InterBase Document Conventions” Lists typefaces and special characters used in this book to describe syntax
and identify object types.
Appendix B, “Data Structures” Lists and describes the data structures, constants, and buffers that are
defined in ibase.h.
TABLE 1.1 API Guide chapters (continued)

Sample database and applications

7KH,QWHU%DVH([DPSOHVVXEGLUHFWRU\FRQWDLQVDVDPSOHGDWDEDVHDQGVDPSOHDSSOLFDWLRQ
VRXUFHFRGH7KHH[DPSOHVLQWKLV$3,*XLGHPDNHXVHRIWKLVVDPSOHGDWDEDVHDQGVRXUFH
FRGHZKHUHYHUSRVVLEOH

API GUIDE 3
 PART I

API PartI

User’s
Guide
3DUW,$3,8VHU·V*XLGH
 CHAPTER

Application Requirements
Chapter2
2
7KLVFKDSWHUVXPPDUL]HVSURJUDPPLQJUHTXLUHPHQWVIRUXVLQJFDWHJRULHVRI$3,IXQFWLRQV
LQGDWDEDVHDSSOLFDWLRQVDQGSURYLGHVFURVVUHIHUHQFHVWRPRUHGHWDLOHGLQIRUPDWLRQLQODWHU
FKDSWHUV
$OO$3,DSSOLFDWLRQVPXVWXVHFHUWDLQ$3,IXQFWLRQVDQGVXSSRUWVWUXFWXUHV)RUH[DPSOHDOO
DSSOLFDWLRQVFRQQHFWWRDWOHDVWRQHGDWDEDVHDQGUXQDWOHDVWRQHWUDQVDFWLRQ$OO
DSSOLFDWLRQVWKHUHIRUHPXVWGHFODUHDQGLQLWLDOL]HGDWDEDVHKDQGOHVDQGWUDQVDFWLRQKDQGOHV
7KH\PD\DOVRQHHGWRGHFODUHDQGSRSXODWHGDWDEDVHSDUDPHWHUEXIIHUV '3%V DQG
WUDQVDFWLRQSDUDPHWHUEXIIHUV 73%V 7KLVFKDSWHURXWOLQHVWKRVHUHTXLUHPHQWVDQGSRLQWV
\RXWRPRUHGHWDLOHGLQIRUPDWLRQODWHULQWKLVERRN
6RPH$3,DSSOLFDWLRQVPD\XVHVSHFLILF$3,IXQFWLRQVVXFKDVWKHIXQFWLRQVWKDWSHUPLWDQ
DSSOLFDWLRQWRSURFHVVG\QDPLF64/ '64/ VWDWHPHQWV7KHVHDSSOLFDWLRQVKDYHDGGLWLRQDO
UHTXLUHPHQWVWKDWDUHDOVRRXWOLQHGLQWKLVFKDSWHUDORQJZLWKSRLQWHUVWRPRUHGHWDLOHG
LQIRUPDWLRQHOVHZKHUHLQWKLVERRN

7
 CHAPTER 2 APPLICATION REQUIREMENTS

Requirements for all applications

7KHIROORZLQJVHFWLRQVRXWOLQHWKHVHUHTXLUHPHQWVIRUDOO$3,DSSOLFDWLRQV
g ,QFOXGLQJLEDVHK
g 'DWDEDVHUHTXLUHPHQWV
g 7UDQVDFWLRQUHTXLUHPHQWV

Including ibase.h
7KH,QWHU%DVHVXEGLUHFWRU\LQFOXGHFRQWDLQVWKHLEDVHKKHDGHUILOHZKLFKVKRXOGEHLQFOXGHG
LQDOOVRXUFHFRGHPRGXOHVIRU$3,DSSOLFDWLRQVLEDVHKFRQWDLQV$3,IXQFWLRQSURWRW\SHV,W
DOVRFRQWDLQVVWUXFWXUHW\SHGHIVSDUDPHWHUGHILQLWLRQVDQGPDFURVUHTXLUHGE\YDULRXV$3,
IXQFWLRQV
7RLQFOXGHLEDVHKLQDVRXUFHFRGHPRGXOHLQVHUWWKHIROORZLQJLQFOXGHQHDUWKHVWDUWRIWKH
VRXUFHFRGH
#include <ibase.h>

,ILEDVHKLVQRWRQ\RXUFRPSLOHU·VVHDUFKSDWK\RXPD\QHHGWRSURYLGHDIXOOSDWK
VSHFLILFDWLRQDQGHQFORVHWKHILOHQDPHLQTXRWDWLRQPDUNV
)DLOXUHWRLQFOXGHLEDVHKFDQSUHYHQWWKHVXFFHVVIXOFRPSLODWLRQDQGOLQNLQJRIDQDSSOLFDWLRQ

Database requirements
$OODSSOLFDWLRQVWKDWZRUNZLWKGDWDEDVHVPXVWSURYLGHRQHGDWDEDVHKDQGOHIRUHDFKGDWDEDVH
WREHDFFHVVHG$GDWDEDVHKDQGOHLVDORQJSRLQWHUWKDWLVXVHGLQ$3,IXQFWLRQVWRDWWDFKWRD
GDWDEDVHDQGWRUHIHUHQFHLWLQVXEVHTXHQW$3,FDOOV7KH,QWHU%DVHKHDGHUILOHLEDVHK
FRQWDLQVDGHILQHXVHIXOIRUGHFODULQJGDWDEDVHKDQGOHV
:KHQHVWDEOLVKLQJDFRQQHFWLRQWRDGDWDEDVHRSWLRQDOGDWDEDVHDWWDFKPHQWFKDUDFWHULVWLFV
VXFKDVDXVHUQDPHDQGSDVVZRUGFRPELQDWLRQFDQEHSDVVHGWRWKHDWWDFKPHQWWKURXJKD
GDWDEDVHSDUDPHWHUEXIIHU '3% 8VXDOO\RQH'3%LVVHWXSIRUHDFKGDWDEDVHDWWDFKPHQW
DOWKRXJKGDWDEDVHDWWDFKPHQWVFDQDOVRVKDUHD'3%

4 'HFODULQJGDWDEDVHKDQGOHV
$GDWDEDVHKDQGOHPXVWEHGHFODUHGDQGLQLWLDOL]HGWR]HUREHIRUHXVH7KHIROORZLQJFRGH
LOOXVWUDWHVKRZWRGHFODUHDQGLQLWLDOL]HDGDWDEDVHKDQGOH
#include <ibase.h>

8 INTERBASE 5
REQUIREMENTS FOR ALL APPLICATIONS

. . .
/* Declare a database handle. */
isc_db_handle db1;
. . .
/* Initialize the handle. */
db1 = 0L;
)RUPRUHLQIRUPDWLRQDERXWGHFODULQJLQLWLDOL]LQJDQGXVLQJGDWDEDVHKDQGOHVVHH&KDSWHU
´:RUNLQJZLWK'DWDEDVHVµ

4 6HWWLQJXSD'3%
$'3%LVDE\WHDUUD\GHVFULELQJRSWLRQDOGDWDEDVHDWWDFKPHQWFKDUDFWHULVWLFV$'3%PXVW
EHVHWXSDQGSRSXODWHGEHIRUHDWWDFKLQJWRDGDWDEDVH3DUDPHWHUVWKDWFDQEHSDVVHGWRWKH
'3%DUHGHILQHGLQLEDVHK
)RUPRUHLQIRUPDWLRQDERXWVHWWLQJXSSRSXODWLQJDQGXVLQJD'3%VHH&KDSWHU
´:RUNLQJZLWK'DWDEDVHVµ

Transaction requirements
$OODSSOLFDWLRQVPXVWSURYLGHRQHWUDQVDFWLRQKDQGOHIRUHDFKWUDQVDFWLRQWREHDFFHVVHG$
WUDQVDFWLRQKDQGOHLVDORQJSRLQWHUWKDWLVXVHGLQ$3,IXQFWLRQVWRVWDUWDWUDQVDFWLRQDQGWR
UHIHUHQFHLWLQVXEVHTXHQW$3,FDOOV7KH,QWHU%DVHKHDGHUILOHLEDVHKFRQWDLQVDGHILQH
XVHIXOIRUGHFODULQJWUDQVDFWLRQKDQGOHV
:KHQVWDUWLQJDWUDQVDFWLRQRSWLRQDOWUDQVDFWLRQFKDUDFWHULVWLFVVXFKDVDFFHVVPHWKRGDQG
LVRODWLRQOHYHOFDQEHSDVVHGWRWKHVWDUWXSFDOOWKURXJKDWUDQVDFWLRQSDUDPHWHUEXIIHU
73% 8VXDOO\RQH73%LVVHWXSIRUHDFKWUDQVDFWLRQDOWKRXJKWUDQVDFWLRQVZLWKWKHVDPH
RSHUDWLQJFKDUDFWHULVWLFVFDQDOVRVKDUHD73%

4 'HFODULQJWUDQVDFWLRQKDQGOHV
$WUDQVDFWLRQKDQGOHPXVWEHGHFODUHGDQGLQLWLDOL]HGWR]HUREHIRUHXVH7KHIROORZLQJFRGH
LOOXVWUDWHVKRZWRGHFODUHDQGLQLWLDOL]HDWUDQVDFWLRQKDQGOH
#include "ibase.h"
. . .
/* Declare a transaction handle. */
isc_tr_handle tr1;
. . .
/* Initialize the handle. */
tr1 = 0L;

API GUIDE 9
 CHAPTER 2 APPLICATION REQUIREMENTS

)RUPRUHLQIRUPDWLRQDERXWGHFODULQJLQLWLDOL]LQJDQGXVLQJWUDQVDFWLRQKDQGOHVVHH&KDSWHU
´:RUNLQJZLWK7UDQVDFWLRQVµ

4 6HWWLQJXSD73%
$73%LVDE\WHDUUD\FRQWDLQLQJSDUDPHWHUVWKDWGHVFULEHRSWLRQDOWUDQVDFWLRQFKDUDFWHULVWLFV
,QWKHVHFDVHVWKH73%PXVWEHVHWXSDQGSRSXODWHGEHIRUHVWDUWLQJDWUDQVDFWLRQ
3DUDPHWHUVWKDWFDQEHSDVVHGWRWKH73%DUHGHILQHGLQLEDVHK
)RUPRUHLQIRUPDWLRQDERXWVHWWLQJXSSRSXODWLQJDQGXVLQJD73%VHH&KDSWHU
´:RUNLQJZLWK7UDQVDFWLRQVµ

Additional requirements
7KHIROORZLQJVHFWLRQVRXWOLQHSRVVLEOHDGGLWLRQDOUHTXLUHPHQWVIRU$3,DSSOLFDWLRQV
GHYHORSHGRQFHUWDLQV\VWHPSODWIRUPVVXFKDV0LFURVRIW:LQGRZVDQGIRUJHQHUDOFODVVHV
RI$3,IXQFWLRQVVXFKDVWKRVHWKDWSURFHVV'64/VWDWHPHQWV

Microsoft Windows requirements

,QWHU%DVHFOLHQWDSSOLFDWLRQVIRU0LFURVRIW:LQGRZVKDYHSURJUDPPLQJUHTXLUHPHQWV
VSHFLILFWRWKDWHQYLURQPHQWDQGWKH&&FRPSLOHUVDYDLODEOHWKHUH
7KH,QWHU%DVHKHDGHUILOHLEDVHKSURYLGHVSURWRW\SHVRIDOO$3,IXQFWLRQV)RU:LQGRZV
DSSOLFDWLRQVWKHVHSURWRW\SHVPDNHXVHRIWKHIROORZLQJGHFODUDWLRQV
#define ISC_FAR __far
#define ISC_EXPORT ISC_FAR __cdecl __loadds __export

)RUH[DPSOHWKHisc_attach_database()SURWRW\SHLQLEDVHKLV
ISC_STATUS ISC_EXPORT isc_attach_database(
ISC_STATUS ISC_FAR *,
short,
char ISC_FAR,
isc_db_handle ISC FAR *,
short,
char ISC_FAR *);

:KHQ:LQGRZVFOLHQWDSSOLFDWLRQVPDNHFDOOVDQGFDVW&GDWDW\SHVWKH\VKRXOGPDNHH[SOLFLW
XVHRIWKH,6&B)$5GHFODUDWLRQ
Note 7KH,6&B(;3257NH\ZRUGLVRPLWWHGIURPWKH$3,IXQFWLRQUHIHUHQFHEHFDXVHRQDOO
QRQ:LQGRZVSODWIRUPVLWLVXQGHILQHG

10 INTERBASE 5
ADDITIONAL REQUIREMENTS

)RUPRUHLQIRUPDWLRQDERXW:LQGRZVUHTXLUHPHQWVVHH&KDSWHU´3URJUDPPLQJZLWK
WKH ,QWHU%DVH $3,µ

DSQL requirements
$3,DSSOLFDWLRQVWKDWEXLOGRUSURPSWIRU'64/TXHULHVDWUXQWLPHUHTXLUHFDUHIXO
GHFODUDWLRQLQLWLDOL]DWLRQDQGSRSXODWLRQRIH[WHQGHG64/GHVFULSWRUDUHD ;64/'$ 
VWUXFWXUHVIRUGDWDWUDQVIHUWRDQGIURPWKHGDWDEDVH,QDGGLWLRQPDQ\$3,IXQFWLRQVVXFK
DVisc_dsql_allocate_statement()DQGisc_dsql_describe()DOVRPDNHXVHRIVWDWHPHQW
KDQGOHVIRU'64/SURFHVVLQJ
LEDVHKSURYLGHVW\SHGHIVIRUWKH;64/'$VWUXFWXUHDQGLWVXQGHUO\LQJVWUXFWXUHWKH
;64/9$5,WDOVRSURYLGHVDGHILQHIRUWKHVWDWHPHQWKDQGOHDPDFURIRUDOORFDWLQJWKH
DSSURSULDWHDPRXQWRIVSDFHIRUDQLQVWDQFHRIDQ;64/'$LQDQDSSOLFDWLRQDQGGHILQHV
IRU'64/LQIRUPDWLRQSDUDPHWHUVSDVVHGWRisc_dsql_sql_info()
7KHIROORZLQJFRGHLOOXVWUDWHVKRZWRGHFODUHDQ;64/'$VWUXFWXUHIRUXVHLQDQDSSOLFDWLRQ
DQGKRZWRGHFODUHDVWDWHPHQWKDQGOH
#include <ibase.h>
. . .
XSQLDA *insqlda;
isc_stmt_handle sql_stmt;
. . .

)RUPRUHLQIRUPDWLRQDERXW'64/SURJUDPPLQJZLWKWKH$3,VHH&KDSWHU´:RUNLQJ
ZLWK'\QDPLF64/µ

Blob requirements
7RZRUNZLWK%OREGDWDWKDWPXVWEHILOWHUHGDQ$3,DSSOLFDWLRQPXVWVHWXSD%ORE
SDUDPHWHUEXIIHU %3% IRUHDFK%ORE$%3%LVDYDULDEOHOHQJWKE\WHYHFWRUGHFODUHGLQDQ
DSSOLFDWLRQWRVWRUHFRQWUROLQIRUPDWLRQWKDWGLFWDWHV%OREDFFHVV7KH%3%FDQFRQWDLQD
QXPEHURIFRQVWDQWVGHILQHGLQLEDVHKWKDWGHVFULEHWKH%OREDQGWKH%OREVXEW\SHVWKDW
VSHFLI\%OREILOWHULQJ

,03257$17 %OREILOWHULQJLVQRWDYDLODEOHRQ1HW:DUHVHUYHUV
$SSOLFDWLRQVWKDWZRUNZLWK%OREGDWDLQDQLQWHUQDWLRQDOHQYLURQPHQWPXVWDOVRGHFODUHDQG
SRSXODWHD%OREGHVFULSWRUWKDWFRQWDLQVFKDUDFWHUVHWLQIRUPDWLRQIRUWKH%ORE7KH%ORE
GHVFULSWRUVWUXFWXUHLVGHILQHGLQLEDVHK7RGHFODUHD%OREGHVFULSWRUDQDSSOLFDWLRQPXVW
SURYLGHFRGHOLNHWKLV

API GUIDE 11
 CHAPTER 2 APPLICATION REQUIREMENTS

#include <ibase.h>
. . .
ISC_BLOB_DESC to_desc;

([FHSWRQ1HW:DUHVHUYHUVZKHUHWKH\DUHQRWVXSSRUWHG%OREILOWHUVHQDEOHD%OREWREH
WUDQVODWHGIURPRQHIRUPDWWRDQRWKHUVXFKDVIURPDFRPSUHVVHGVWDWHWRDQGHFRPSUHVVHG
VWDWHRUYLFHYHUVD,I%OREILOWHUVDUHGHVLUHGVHSDUDWHILOWHUIXQFWLRQVPXVWEHFUHDWHGDQG
GHILQHGWRWKHGDWDEDVHWRHQVXUHWKHLUXVHZKHQ%OREGDWDLVDFFHVVHG
)LQDOO\WRDFFHVV%OREGDWDDSSOLFDWLRQVPXVWPDNHH[WHQVLYHXVHRI$3,'64/IXQFWLRQV
)RUPRUHLQIRUPDWLRQDERXWZRUNLQJZLWK%OREGDWDDQG%OREILOWHUVVHH
&KDSWHU´:RUNLQJZLWK%ORE'DWDµ)RUPRUHLQIRUPDWLRQDERXW'64/VHH&KDSWHU
´:RUNLQJZLWK'\QDPLF64/µ

Array requirements
$3,IXQFWLRQVWKDWKDQGOHDUUD\SURFHVVLQJUHTXLUHWKHXVHRIDQDUUD\GHVFULSWRUVWUXFWXUH
DQGDUUD\,'VGHILQHGLQLEDVHK,QDGGLWLRQDSSOLFDWLRQVDFFHVVLQJDUUD\VPXVWPDNH
H[WHQVLYHXVHRI$3,'64/IXQFWLRQV
7KHIROORZLQJFRGHLOOXVWUDWHVKRZWRGHFODUHDQDUUD\GHVFULSWRUDQGDUUD\,'YDULDEOHDQG
KRZWRLQLWLDOL]HDQDUUD\,'WR]HUREHIRUHXVH
#include <ibase.h>
. . .
ISC_ARRAY_DESC desc;
ISC_QUAD array_id;
. . .
array_id = 0L;
. . .

)RUPRUHLQIRUPDWLRQDERXWZRUNLQJZLWKDUUD\VVHH&KDSWHU´:RUNLQJZLWK$UUD\
'DWDµ)RUPRUHLQIRUPDWLRQDERXW'64/VHH&KDSWHU´:RUNLQJZLWK'\QDPLF64/µ

Event requirements
,QWHU%DVHHYHQWVDUHPHVVDJHVSDVVHGIURPDWULJJHURUVWRUHGSURFHGXUHWRDQDSSOLFDWLRQWR
DQQRXQFHWKHRFFXUUHQFHRIVSHFLILHGFRQGLWLRQVRUDFWLRQVXVXDOO\GDWDEDVHFKDQJHVVXFKDV
LQVHUWLRQVPRGLILFDWLRQVRUGHOHWLRQVRIUHFRUGV

12 INTERBASE 5
COMPILING AND LINKING

%HIRUHDQDSSOLFDWLRQFDQUHVSRQGWRDQHYHQWLWPXVWUHJLVWHULQWHUHVWLQDQHYHQW7RUHJLVWHU
LQWHUHVWLQDQHYHQWWKHDSSOLFDWLRQPXVWHVWDEOLVKDQGSRSXODWHWZRHYHQWSDUDPHWHUEXIIHUV
(3%V RQHIRUKROGLQJWKHLQLWLDORFFXUUHQFHFRXQWYDOXHVIRUHDFKHYHQWRILQWHUHVWDQG
DQRWKHUIRUKROGLQJWKHFKDQJHGRFFXUUHQFHFRXQWYDOXHV7KHVHEXIIHUVDUHSDVVHGDV
SDUDPHWHUVWRVHYHUDO$3,HYHQWIXQFWLRQVDQGDUHXVHGWRGHWHUPLQHZKLFKHYHQWVKDYH
RFFXUUHG
,Q&HDFK(3%LVGHFODUHGDVDFKDUSRLQWHUDVIROORZV
char *event_buffer, *result_buffer;

2QFHWKHEXIIHUVDUHGHFODUHGisc_event_block()LVFDOOHGWRDOORFDWHVSDFHIRUWKHPDQGWR
SRSXODWHWKHPZLWKVWDUWLQJYDOXHV
)RUPRUHLQIRUPDWLRQDERXWHYHQWVVHH&KDSWHU´:RUNLQJZLWK(YHQWVµ

Error-handling requirements
0RVW$3,IXQFWLRQVUHWXUQVWDWXVLQIRUPDWLRQLQDQHUURUVWDWXVYHFWRUDQDUUD\RIORQJV7R
KDQGOH,QWHU%DVHHUURUFRQGLWLRQVVKRXOGWKH\DULVHDSSOLFDWLRQVVKRXOGGHFODUHDVWDWXV
YHFWRUDVIROORZV
#include <ibase.h>
. . .
ISC_STATUS status_vector[20];

,6&B67$786LVDGHILQHLQLEDVHKSURYLGHGIRUSURJUDPPLQJFRQYHQLHQFHDQGSODWIRUP
LQGHSHQGHQFH
LEDVHKDOVRFRQWDLQVGHILQHVIRUDOO,QWHU%DVHHUURUFRQGLWLRQV$SSOLFDWLRQVFDQXVH$3,
HUURUKDQGOLQJIXQFWLRQVWRFRQVWUXFWHUURUPHVVDJHVIURPWKHVWDWXVYHFWRUWKDWDUHEDVHG
RQWKHVHHUURUFRQGLWLRQVRUFDQH[DPLQHWKHVWDWXVYHFWRUGLUHFWO\IRUSDUWLFXODUHUURU
FRQGLWLRQVXVLQJWKHGHILQHVLQSODFHRIHUURUQXPEHUV8VLQJGHILQHVLQWKLVPDQQHU
PDNHVVRXUFHFRGHHDVLHUWRXQGHUVWDQGDQGPDLQWDLQ
)RUPRUHLQIRUPDWLRQDERXWHUURUKDQGOLQJVHH&KDSWHU´:RUNLQJZLWK(YHQWVµ

Compiling and linking

2QPRVWGHYHORSPHQWSODWIRUPVDQ$3,DSSOLFDWLRQLVFRPSLOHGOLNHDQ\VWDQGDUG&RU&
DSSOLFDWLRQ)RUPRUHLQIRUPDWLRQDERXWDSDUWLFXODUFRPSLOHUFRQVXOWWKHFRPSLOHU·V
GRFXPHQWDWLRQ

API GUIDE 13
 CHAPTER 2 APPLICATION REQUIREMENTS

2QPRVWSODWIRUPV,QWHU%DVHVXSSRUWVG\QDPLFOLQNLQJRILWVOLEUDU\DWUXQWLPH
2QHH[FHSWLRQWRWKLVVFHQDULRLVRQ0LFURVRIW:LQGRZVZKHUHDQDSSOLFDWLRQPXVWH[SOLFLWO\
OLQNWRWKH,QWHU%DVHOLEUDU\ JGVOLERUJGVBPVOLE 
2Q0LFURVRIW:LQGRZVWKHUHDUHSDUWLFXODUFRPSLOLQJRSWLRQVWREHDZDUHRI)RUPRUH
LQIRUPDWLRQDERXWOLQNLQJXQGHU:LQGRZVVHH&KDSWHU´3URJUDPPLQJZLWK
WKH ,QWHU%DVH $3,µ
)RUDOORWKHUSODWIRUPVVHHWKH,QWHU%DVH3URJUDPPHU·V*XLGHIRUVSHFLILFFRPSLOLQJDQGOLQNLQJ
JXLGHOLQHV

14 INTERBASE 5
 CHAPTER

Programming with
Chapter3
3
the InterBase API

7KLVFKDSWHUSURYLGHVLQIRUPDWLRQVSHFLILFWRSURJUDPPLQJ,QWHU%DVHDSSOLFDWLRQVRQD
FOLHQWZLWK&&,WDVVXPHVIDPLOLDULW\ZLWK%RUODQG&&RU0LFURVRIW&&
,QWHU%DVHDQGWKH,QWHU%DVHGRFXPHQWDWLRQVHWSDUWLFXODUO\WKH/DQJXDJH5HIHUHQFH

Basic procedure for application development

7KHEDVLFVWHSVLQDSSOLFDWLRQGHYHORSPHQWRQWKH,QWHU%DVH:LQGRZV&OLHQWDUH
g 'HWHUPLQHZKLFKFOLHQWDQGVHUYHUSODWIRUPVWKHDSSOLFDWLRQZLOOUXQRQ,QWHU%DVHFOLHQWV
DQGVHUYHUVLQFOXGH0LFURVRIW:LQGRZV:LQGRZV17DQG8QL[$QROGHUYHUVLRQRIWKH
,QWHU%DVHVHUYHULVDYDLODEOHIRU1RYHOO1HW:DUH
g &RGHWKHDSSOLFDWLRQLQ&RU&2Q81,;,QWHU%DVHDOVRVXSSRUWVFRPSLOHUVIRU&2%2/
$'$DQG)2575$1
g &RPSLOHDQGOLQNWKHDSSOLFDWLRQ
g 7HVWDQGGHEXJWKHDSSOLFDWLRQ
g 'HSOR\WKHDSSOLFDWLRQRQWKHSURGXFWLRQFOLHQWSODWIRUP

15
 CHAPTER 3 PROGRAMMING WITH THE INTERBASE API

Supported development environments

7KH,QWHU%DVHFOLHQWOLEUDU\HQDEOHVGHYHORSHUVWRGHVLJQ,QWHU%DVH64/FOLHQWDSSOLFDWLRQV
WKDWFRQQHFWWRUHPRWH,QWHU%DVHVHUYHUVRQ:LQGRZV:LQGRZV178QL[RU1HW:DUH
6HHWKH2SHUDWLRQV*XLGHIRUPRUHVSHFLILFLQIRUPDWLRQDERXWWKLVWRSLF

User name and password requirements

:KHQDQ,QWHU%DVHFOLHQWDSSOLFDWLRQLVFRPSLOHGOLQNHGDQGUXQWKHFOLHQWPXVWDOZD\VVHQG
DYDOLGXVHUQDPHDQGSDVVZRUGFRPELQDWLRQWRWKH,QWHU%DVHVHUYHU7KHVHUYHUFKHFNVWKH
XVHUQDPHDQGSDVVZRUGDJDLQVWWKHXVHUQDPHDQGSDVVZRUGFRPELQDWLRQVVWRUHGLQLWV
VHFXULW\GDWDEDVH,IDPDWFKLVIRXQGWKHFOLHQWFDQDWWDFKWR,QWHU%DVHGDWDEDVHVRQWKH
VHUYHU,IDPDWFKLVQRWIRXQGDWWDFKPHQWLVGHQLHG
)RUDVXFFHVVIXODWWDFKPHQWWRRFFXUWKHIROORZLQJVWHSVPXVWEHWDNHQ
 $XVHUZLWK6<6'%$SULYLOHJHVPXVWDGGDFOLHQW·VXVHUQDPHDQGSDVVZRUGWRWKH
VHUYHU·VVHFXULW\GDWDEDVH LVFJGE 8VHWKH6HUYHU0DQDJHUWRGRWKLVRQ
:LQGRZVSODWIRUPV2Q81,;XVHWKHgsecXWLOLW\
 7KHFOLHQWPXVWVHQGDYDOLGXVHUQDPHDQGSDVVZRUGFRPELQDWLRQWRWKHVHUYHU
3DVVZRUGLVFDVHVHQVLWLYH
Note 8QGHUVRPHFLUFXPVWDQFHV\RXFDQFRQQHFWWRDGDWDEDVHHYHQLI\RXGRQ·WKDYHDXVHU
QDPHLQWKH,QWHU%DVHVHFXULW\GDWDEDVH,QRUGHUIRUWKLVWRKDSSHQWKHIROORZLQJWKLQJV
PXVWEHWUXH
à %RWKWKHFOLHQWDQGVHUYHUDUHUXQQLQJXQGHU81,;
à <RXUFXUUHQWORJLQH[LVWVRQWKHVHUYHUKRVW
à <RXDUHORJJLQJLQIURPDWUXVWHGFOLHQWDWUXVWHGFOLHQWLVRQHWKDWLVOLVWHGLQWKH
HWFKRVWVHTXLYRUHWFJGVBKRVWVHTXLYILOHRQWKHVHUYHURULQWKH UKRVWVILOHLQ\RXUKRPH
GLUHFWRU\RQWKHVHUYHU
à <RXKDYHQRWVSHFLILHGDXVHUQDPHDQGSDVVZRUGLQWKHFRQQHFWVWULQJ

16 INTERBASE 5
SPECIFYING USER NAME AND PASSWORD

Specifying user name and password

$FOLHQWDSSOLFDWLRQPXVWVSHFLI\DXVHUQDPHDQGSDVVZRUGZKHQLWDWWDFKHVWRDGDWDEDVH
)DLOXUHWRSURYLGHDYDOLGXVHUQDPHDQGSDVVZRUGFRPELQDWLRQUHVXOWVLQDQHUURU8VHWKH
IROORZLQJPHWKRGVWRSURYLGHXVHUQDPHVDQGSDVVZRUGV
g &UHDWHDGDWDEDVHSDUDPHWHUEORFN '3% ZLWKLVFBGSEBXVHUBQDPHDQGLVFBGSEBSDVVZRUGDQG
SDVVWKHSDUDPHWHUEORFNXVLQJisc_attach_database()
g $GGLVFBGSEBXVHUBQDPHDQGLVFBGSEBSDVVZRUGSDUDPHWHUVWRDQH[LVWLQJ'3%ZLWK
isc_expand_dpb()
)RUPRUHLQIRUPDWLRQDERXWWKH'3%isc_attach_database()DQGisc_expand_dpb()VHH
&KDSWHU´:RUNLQJZLWK'DWDEDVHVµ

Using environment variables

,QWHU%DVHFOLHQWDSSOLFDWLRQVFDQXVHWKUHHHQYLURQPHQWYDULDEOHVWRHVWDEOLVKSURJUDP
SDUDPHWHUV7KHVHYDULDEOHVPXVWEHVHWVRWKDWWKH\DUHDYDLODEOHWRWKHDSSOLFDWLRQZKHQLW
LVUXQQLQJ)RUH[DPSOHVHWWLQJWKHVHYDULDEOHVZLWKLQD'26ZLQGRZDIWHU:LQGRZVKDV
EHHQVWDUWHGGRHVQRWDIIHFWDQ\:LQGRZVSURJUDPVEXWDIIHFWV'26DSSOLFDWLRQVLQWKDW
ZLQGRZ
7KHIROORZLQJWDEOHVXPPDUL]HVWKHVHYDULDEOHVDQGWKHLUXVHV

Variable Purpose Example

ISC_DATABASE Specifies a default server and database SET ISC_DATABASE =
directory to use on the remote server ingold:/usr/interbase/examples
ISC_USER Specifies a user name for the PC client SET ISC_USER = HERMES
application
ISC_PASSWORD Specifies a case-sensitive password for SET_PASSWORD = Ichneumon
the PC client application
TABLE 3.1 Environment variables used by InterBase

7KH,6&B86(5DQG,6&B3$66:25'HQYLURQPHQWYDULDEOHVDUHXVHGWRJHWKHUWRHVWDEOLVKD
YDOLGXVHUQDPHDQGSDVVZRUGFRPELQDWLRQWRSDVVWRWKHUHPRWH,QWHU%DVHGDWDEDVHVHUYHU

,03257$17 'RQRWXVHWKH,6&B3$66:25'HQYLURQPHQWYDULDEOHZKHQVHFXULW\LVDFRQFHUQ$Q\RQH
ZLWKDFFHVVWRDFOLHQWZKHUHDQ,6&B3$66:25'HQYLURQPHQWYDULDEOHLVGHILQHGLQDILOH
VXFKDVDXWRH[HFEDWFDQHDVLO\YLHZWKHSDVVZRUG

API GUIDE 17
 CHAPTER 3 PROGRAMMING WITH THE INTERBASE API

Setting a default database directory

7RFRQQHFWDXWRPDWLFDOO\WRDGHIDXOWGDWDEDVHGLUHFWRU\RQDUHPRWHVHUYHUFUHDWHWKH
,6&B'$7$%$6(HQYLURQPHQWYDULDEOHDQGVHWLWWRWKHIXOOSDWKVSHFLILFDWLRQIRUWKHGHVLUHG
GDWDEDVHGLUHFWRU\LQFOXGLQJKRVWDQGSDWKQDPHV
Note +RVWQDPHVSHFLILFDWLRQLVVSHFLILFWRWKHVHUYHU·VRSHUDWLQJV\VWHPDQGQHWZRUN
SURWRFRO7KHKRVWV\QWD[LQWKHSUHYLRXVH[DPSOHLVIRUDJHQHULF8QL[VHUYHU)RURWKHU
VHUYHUVDQGRSHUDWLQJV\VWHPVVHHWKDWV\VWHP·VUHIHUHQFHPDQXDOV

Setting a user name and password

7RVHWXSDGHIDXOWXVHUQDPHDQGSDVVZRUGIRUXVHRQD3&FOLHQWFUHDWHWZRQHZ
HQYLURQPHQWYDULDEOHV,6&B86(5DQG,6&B3$66:25'
(YHQLI,6&B86(5DQG,6&B3$66:25'DUHVHWDGLIIHUHQWXVHUQDPHDQGSDVVZRUGPD\EH
VSHFLILHGLQD'3%XVHGDVDQDUJXPHQWWRisc_attach_database()$XVHUQDPHRUSDVVZRUG
VSHFLILHGLQDGDWDEDVHSDUDPHWHUEORFNRYHUULGHVWKH26HQYLURQPHQWYDULDEOHV
Note 8VLQJHQYLURQPHQWYDULDEOHVLQWKLVPDQQHULVQRWVHFXUHDQGWKHUHIRUHQRW
UHFRPPHQGHG

Datatypes
,QWHU%DVHVXSSRUWVDZLGHYDULHW\RIGDWDW\SHVIRUDSSOLFDWLRQGHYHORSPHQW7KHVHGDWDW\SHV
DUHGHILQHGLQDW\SHGHIWREHSODWIRUPLQGHSHQGHQW7KH,QWHU%DVHFOLHQWOLEUDULHVDUHDOVR
FRPSLOHGZLWKSDFNHGGDWDVWUXFWXUHVWREHFRPSDWLEOHZLWKDYDULHW\RISODWIRUPV
)RUPRUHLQIRUPDWLRQDERXW,QWHU%DVHGDWDW\SHVVHHWKH/DQJXDJH5HIHUHQFH

Calling conventions
&RQYHQWLRQVIRUFDOOLQJIXQFWLRQVYDU\IURPSODWIRUPWRSODWIRUP6SHFLILFDOO\
g 2Q81,;SODWIRUPVXVHWKH&FDOOLQJFRQYHQWLRQV FGHFO LQDOOFDVHV
g 2Q:LQGRZVDQG:LQGRZV17XVHWKHVWDQGDUGFDOOLQJFRQYHQWLRQV BVWGFDOO IRUDOO
IXQFWLRQVWKDWKDYHDIL[HGQXPEHURIDUJXPHQWV7KHUHDUHRQO\WKUHHIXQFWLRQVWKDWKDYHD
YDULDEOHQXPEHURIDUJXPHQWV)RUWKHVHWKUHH³isc_start_transaction(),
isc_expand_dpb()DQGisc_event_block()³XVHWKHFGHFOFRQYHQWLRQV

18 INTERBASE 5
BUILDING APPLICATIONS

Building applications
7KLVVHFWLRQGLVFXVVHVFRPSLOHUVDQGOLEUDULHVWKDWDUHQHHGHGWREXLOG,QWHU%DVHDSSOLFDWLRQV
HELP WITH LINKING AND COMPILING 2QHDFKSODWIRUPWKHUHLVDPDNHILOHLQWKHH[DPSOHV
GLUHFWRU\WKDWFRQWDLQVGHWDLOHGSODWIRUPVSHFLILFLQIRUPDWLRQDERXWOLQNLQJDQGFRPSLOLQJ
2SHQWKHPDNHILOHLQDWH[WHGLWRUWRDFFHVVWKHLQIRUPDWLRQ

Compilers
7KHLPSRUWOLEUDULHVLQFOXGHGZLWK,QWHU%DVHKDYHEHHQWHVWHGZLWKWKHIROORZLQJFRPSLOHUV

Windows platforms
g %RUODQG&
g 0LFURVRIW9LVXDO&
g 0LFURVRIW9LVXDO&

Solaris
g & 63$5&:RUNV6&&FRPSLOHU
g & 63$5&:RUNV6&&FRPSLOHU
g &2%2/ 0LFUR)RFXV&RERO
g $'$ 63$5&:RUNV6&$GDFRPSLOHU
g )2575$1 63$5&:RUNV6&)RUWUDQFRPSLOHU

HP-UX
g & +3&+38;9HUVLRQ$
g & +3&+38;9HUVLRQ$
g &2%2/ 0LFUR)RFXV&RERO
g $'$ $OV\V$GD$GD:RUOG9
g )2575$1 +3)RUWUDQ5HOHDVH

API GUIDE 19
 CHAPTER 3 PROGRAMMING WITH THE INTERBASE API

Linking
7KH,QWHU%DVHOLEUDU\ILOHVUHVLGHLQWKHOLEVXEGLUHFWRU\RIWKHLQVWDOODWLRQGLUHFWRU\
$SSOLFDWLRQVPXVWOLQNZLWKWKH,QWHU%DVHFOLHQWOLEUDU\7KLVOLEUDU\QDPHYDULHVGHSHQGLQJ
RQWKHSODWIRUPDQGWKHFRPSLOHU

Platform/compiler InterBase library file

Windows/Borland C++ gds32.lib
Windows/Microsoft Visual C++ 2.0 and 4.0 gds32_ms.lib
Solaris/all gdsmt
HPUX/all gds
TABLE 3.2 InterBase library file names

%RUODQGFRPSLOHUVHDUOLHUWKDQGRQRWZRUNZLWKJGVOLE

Include files
$SSOLFDWLRQVPXVWLQFOXGHWKHLEDVHKKHDGHUILOHWRSLFNXSWKH,QWHU%DVHW\SHGHILQLWLRQVDQG
IXQFWLRQSURWRW\SHV7KLVILOHLVLQWKHLQFOXGHVXEGLUHFWRU\RIWKH,QWHU%DVHLQVWDOOGLUHFWRU\
2Q81,;SODWIRUPVWKHJGVKILOHLVDYDLODEOHLQWKHLQVWDOODWLRQGLUHFWRU\IRUEDFNZDUG
FRPSDWLELOLW\

Using Microsoft C++

8VHWKHIROORZLQJRSWLRQVZKHQFRPSLOLQJDSSOLFDWLRQVZLWK0LFURVRIW&

Option Action
c Compile without linking (DLLs only)
Zi Generate complete debugging information
DWIN32 Defines “WIN32” to be the null string
D_MT Use a multi-thread, statically-linked library
TABLE 3.3 Microsoft C compiler options

20 INTERBASE 5
BUILDING APPLICATIONS

)RUH[DPSOHWKHVHFRPPDQGVXVHWKH0LFURVRIWFRPSLOHUWREXLOGD'//WKDWXVHV
,QWHU%DVH
cl -c -Zi -DWIN32 -D_MT -LD udf.c
lib -out:udf.lib -def:funclib.def -machine:i386 -subsystem:console
link -DLL -out:funclib.dll -DEBUG:full,mapped -DEBUGTYPE:CV
-machine:i386 -entry:_DllMainCRTStartup@12 -subsystem:console
-verbose udf.obj udf.exp gds32.lib crtdll.lib

7KLVFRPPDQGEXLOGVDQ,QWHU%DVHH[HFXWDEOHXVLQJWKH0LFURVRIWFRPSLOHU
cl -Zi -DWIN32 -D_MT -MD udftest.c udf.lib gds32.lib crtdll.lib

USING THE DYNAMIC RUNTIME LIBRARY ,I\RXDUH

à XVLQJD0LFURVRIW9LVXDO&RU0LFURVRIW9LVXDO&
à FRPSLOLQJDQGOLQNLQJVHSDUDWHO\DQG
à XVLQJWKH'\QDPLF5XQWLPH/LEUDU\ PVYFUWGOORUPVYFUWGOO 
\RXQHHGWRXVHWKH0'FRPSLOHUIODJWRFRPSLOHZLWKWKHUXQWLPHOLEUDU\ 57/ DVZHOO
DVOLQNLQJZLWKWKHFRUUHFWLPSRUWOLEUDU\

Using Borland C/C++

8VHWKHIROORZLQJRSWLRQVZKHQFRPSLOLQJDSSOLFDWLRQVZLWK%RUODQG&

Option Action
v Turns on source debugging
a4 Structure padding/byte alignment
DWIN32 Defines the string “WIN32”; with no argument, it defines it to the null string
tWM Makes the target multi-threaded
tWC: Makes the target a console .EXE with all functions exportable; cannot be used with
the -tWCD option
tWCD Makes the target a console .DLL with all functions exportable; cannot be used with
the -tWC option
TABLE 3.4 Borland C compiler options

)RUH[DPSOHWKLVFRPPDQGFUHDWHVD'//QDPHGIXQFOLEGOOIURPDVRXUFHILOHQDPHGXGIF

API GUIDE 21
 CHAPTER 3 PROGRAMMING WITH THE INTERBASE API

implib mygds32.lib \interbas\bin\gds32.dll

bcc32 -v -a4 -DWIN32 -tWM -tWCD -efunclib.dll udf.c mygds32.lib

7KHIROORZLQJFRPPDQGVFUHDWHDQ,QWHU%DVHH[HFXWDEOHQDPHGXGIWHVWH[H ZKLFKFDOOVLQWR
IXQFOLEGOO IURPDVRXUFHILOHQDPHGXGIWHVWHFRQWDLQLQJHPEHGGHG64/FRPPDQGV
implib udf.lib funclib.dll
gpre -e udftest.e
bcc32 -v -a4 -DWIN32 -tWM -tWC udftest.c udf.lib mygds32.lib

:KHQOLQNLQJDSSOLFDWLRQVZLWK%RUODQG&FRPPDQGOLQHOLQNHUXVHWKHFRSWLRQ FDVH
VHQVLWLYHOLQN 
Note 7KHUHDUHHTXLYDOHQWJHQHUDOOLQNHURSWLRQVZLWKLQWKH%RUODQG,QWHJUDWHG
'HYHORSPHQW(QYLURQPHQW ,'( 7KHGHIDXOWLQWKH,'(LVFDVHVHQVLWLYHOLQN FRSWLRQ 
DORQHZKLFKFDXVHVXQUHVROYHGOLQNHUHUURUVIRUDOORIWKH,QWHU%DVHHQWU\SRLQWV
8VHWKHIROORZLQJRSWLRQVZKHQFRPSLOLQJDSSOLFDWLRQVZLWK%RUODQG&&

Using the Borland integrated development environment (IDE)

7KH%RUODQG,QWHJUDWHG'HYHORSPHQW(QYLURQPHQW ,'( RIIHUVRSWLRQVWKDWDUHHTXLYDOHQW
WRWKHFRPPDQGOLQHRSWLRQV

4 ,'(GHIDXOW
7KHFDVHVHQVLWLYHOLQN FRSWLRQ LVWKHGHIDXOWLQWKH,'(

4 ,'(3URMHFW2SWLRQVGLDORJER[
&KRRVHWKHIROORZLQJRSWLRQVIURPWKH,'(3URMHFW2SWLRQVGLDORJER[7KHFRUUHVSRQGLQJ
FRPPDQGOLQHRSWLRQLVDOVROLVWHG

DIRECTORIES
,QFOXGHGLUHFWRU\F?3URJUDP)LOHV?,QWHU%DVH&RUS?,QWHU%DVH?LQFOXGH
/LEUDU\GLUHFWRU\F?3URJUDP)LOHV?,QWHU%DVH&RUS?,QWHU%DVH?OLE
Note 7KLVSDWKVSHFLILFDWLRQDVVXPHVWKDW,QWHU%DVHZDVLQVWDOOHGLQWKH
F?3URJUDP )LOHV?,QWHU%DVH&RUS?,QWHU%DVHGLUHFWRU\

COMPILER
6RXUFHODQJXDJHFRPSOLDQFH%RUODQGH[WHQVLRQV
ELW&RPSLOHU

22 INTERBASE 5
BUILDING APPLICATIONS

'DWDDOLJQPHQW%\WH DRSWLRQIRUE\WHDOLJQPHQW

LINKER
&KRRVH&DVHVHQVLWLYHOLQN21 FRSWLRQ 

Module definition file

7KH67$&.6,=(SDUDPHWHUVKRXOGEHVHWWRDWOHDVWNLORE\WHV E\WHV EXW
NLORE\WHV E\WHV LVUHFRPPHQGHG$VDPSOH GHIILOHLVLQFOXGHGLQWKHH[DPSOHV
VXEGLUHFWRU\RIWKH,QWHU%DVHLQVWDOODWLRQGLUHFWRU\

Using dynamic link libraries (DLLs)

,QWHU%DVHDSSOLFDWLRQVXVHWKHJGVGOOG\QDPLFOLQNOLEUDU\ZKLFKLQWXUQORDGVWKHDSSURSULDWH
QHWZRUN'//V7KHVH'//VXQORDGDXWRPDWLFDOO\ZKHQWKHODVWFDOOLQJDSSOLFDWLRQ
WHUPLQDWHV,IWKHFDOOLQJDSSOLFDWLRQH[LWVDEQRUPDOO\ IRUH[DPSOHIURPDSURWHFWLRQIDXOW 
LWLVSRVVLEOHWKDW'//VZLOOQRWEHXQORDGHGIURPPHPRU\,IWKLVRFFXUVH[LWDQGUHVWDUW
:LQGRZVWRIUHHWKHUHVRXUFHV

Example programs
([DPSOHSURJUDPVGHPRQVWUDWLQJKRZWRXVHWKH,QWHU%DVH$3,DUHLQFOXGHGLQWKHH[DPSOHV
VXEGLUHFWRU\RIWKH,QWHU%DVHLQVWDOODWLRQGLUHFWRU\7KHUHLVDOVRDVDPSOH GHIILOH
2Q17WKHUHDUHWZRPDNHILOHVPDNHILOHEFIRUWKH%RUODQGFRPSLOHUDQGOLQNHUDQG
PDNHILOHPVFIRUWKH0LFURVRIWFRPSLOHUDQGOLQNHU,QERWKILOHV\RXPXVWPRGLI\WKH,%$6(
HQYLURQPHQWYDULDEOHWRSRLQWWRDQDEVROXWHSDWK
,QWKH EFPDNHILOHPRGLI\WKH%&',5YDULDEOHWRSRLQWWRWKHDEVROXWHSDWKWRWKH%RUODQG
FRPSLOHUDQGOLQNHU
,QWKH PVFPDNHILOHPRGLI\WKH06&',5YDULDEOHWRSRLQWWRWKHDEVROXWHSDWKWRWKH
0LFURVRIWFRPSLOHUDQGOLQNHU
7REXLOGWKHH[DPSOHDSSOLFDWLRQVRQ17XVLQJ%RUODQG&XVHWKHIROORZLQJFRPPDQG
make -B -f makefile.bc all

7REXLOGWKHH[DPSOHDSSOLFDWLRQVXVLQJ0LFURVRIW&XVHWKLVFRPPDQG
nmake -B -f makefile.msc all

API GUIDE 23
 CHAPTER 3 PROGRAMMING WITH THE INTERBASE API

2Q81,;V\VWHPVWKHFRPPDQGWREXLOGWKHH[DPSOHDSSOLFDWLRQVLVDVIROORZV
make all

24 INTERBASE 5
 CHAPTER

Working with Databases

Chapter4
4
7KLVFKDSWHUGHVFULEHVKRZWRVHWXSDGDWDEDVHSDUDPHWHUEXIIHU '3% WKDWVSHFLILHVGDWDEDVH
DWWDFKPHQWSDUDPHWHUVKRZWRVHWXSDQGLQLWLDOL]HGDWDEDVHKDQGOHVDQGKRZWRXVHWKHILYH
$3,IXQFWLRQVWKDWFRQWUROGDWDEDVHDFFHVV,WDOVRH[SODLQVKRZWRVHWXSLWHPUHTXHVWDQG
UHWXUQEXIIHUVSULRUWRUHWULHYLQJLQIRUPDWLRQDERXWDQDWWDFKHGGDWDEDVH

25
 CHAPTER 4 WORKING WITH DATABASES

7KHIROORZLQJWDEOHOLVWVWKH$3,IXQFWLRQVIRUZRUNLQJZLWKGDWDEDVHV7KHIXQFWLRQVDUH
OLVWHGLQWKHRUGHUWKDWWKH\W\SLFDOO\DSSHDULQDQDSSOLFDWLRQ

Call Purpose
isc_expand_dpb() Specifies additional parameters for database access, such as user names and
passwords elicited from a user at run time; uses a previously declared and
populated DPB
isc_attach_database() Connects to a database and establishes initial parameters for database access,
such as number of cache buffers to use; uses a previously declared and
populated DPB
isc_database_info() Retrieves requested information about an attached database, such as the
version of the on-disk structure (ODS) that it uses
isc_detach_database() Disconnects from an attached database and frees system resources allocated
to that attachment
isc_drop_database() Deletes a database and any support files, such as shadow files
TABLE 4.1 API database functions

Connecting to databases
&RQQHFWLQJWRRQHRUPRUHGDWDEDVHVLVDIRXUVWHSSURFHVV
 &UHDWLQJDQGLQLWLDOL]LQJDGDWDEDVHKDQGOHIRUHDFKGDWDEDVHWREHDWWDFKHG
 &UHDWLQJDQGSRSXODWLQJD'3%IRUHDFKGDWDEDVHWREHDWWDFKHG
 2SWLRQDOO\FDOOLQJisc_expand_dpb()SULRUWRDFWXDODWWDFKPHQWWRDGGPRUH
GDWDEDVHSDUDPHWHUVWRDSUHYLRXVO\FUHDWHGDQGSRSXODWHG'3%
 &DOOLQJisc_attach_database()IRUHDFKGDWDEDVHWRZKLFKWRFRQQHFW
7KHVHVWHSVDUHGHVFULEHGLQWKHIROORZLQJVHFWLRQVRIWKLVFKDSWHU

Creating database handles

(YHU\GDWDEDVHWKDWLVDFFHVVHGLQDQDSSOLFDWLRQPXVWEHDVVRFLDWHGZLWKLWVRZQGDWDEDVH
KDQGOHDSRLQWHUWRD),/(VWUXFWXUHWKDWLVXVHGE\DOO$3,GDWDEDVHIXQFWLRQV7KHLEDVHK
KHDGHUILOHFRQWDLQVWKHIROORZLQJ&W\SHGHIGHFODUDWLRQIRUGDWDEDVHKDQGOHV
typedef void ISC_FAR *isc_db_handle;

26 INTERBASE 5
CONNECTING TO DATABASES

7RXVHWKLVW\SHGHIIRUGHFODULQJGDWDEDVHKDQGOHVLQDQDSSOLFDWLRQLQFOXGHLEDVHKLQHDFK
VRXUFHILOHPRGXOH
#include <ibase.h>

4 'HFODULQJGDWDEDVHKDQGOHV
7RHVWDEOLVKGDWDEDVHKDQGOHVIRUXVHGHFODUHDYDULDEOHRIW\SHLVFBGEBKDQGOHIRUHDFKGDWDEDVH
WKDWZLOOEHDFFHVVHGDWWKHVDPHWLPH7KHIROORZLQJFRGHGHFODUHVWZRKDQGOHV
#include <ibase.h>
. . .
isc_db_handle db1;
iac_db_handle db2;

2QFHDGDWDEDVHLVQRORQJHUDWWDFKHGLWVKDQGOHFDQEHDVVLJQHGWRDGLIIHUHQWGDWDEDVHLQD
VXEVHTXHQWDWWDFKPHQW,IDQDSSOLFDWLRQDFFHVVHVVHYHUDOGDWDEDVHVEXWRQO\DFFHVVHVD
VXEVHWRIGDWDEDVHVDWWKHVDPHWLPHLWLVRQO\QHFHVVDU\WRGHFODUHDVPDQ\KDQGOHVDVWKHUH
ZLOOEHVLPXOWDQHRXVGDWDEDVHDFFHVVHV)RUH[DPSOHLIDQDSSOLFDWLRQDFFHVVHVDWRWDORIWKUHH
GDWDEDVHVEXWRQO\DWWDFKHVWRWZRRIWKHPDWDWLPHRQO\WZRGDWDEDVHKDQGOHVQHHGEH
GHFODUHG

4 ,QLWLDOL]LQJGDWDEDVHKDQGOHV
%HIRUHDGDWDEDVHKDQGOHFDQEHXVHGWRDWWDFKWRDGDWDEDVHLWPXVWEHVHWWR]HUR7KH
IROORZLQJFRGHLOOXVWUDWHVKRZWZRGDWDEDVHKDQGOHVDUHVHWWR]HUR
#include <ibase.h>
. . .
isc_db_handle db1;
isc_db_handle db2;
. . .
/* Set database handles to zero before attaching to a database. */
db1 = 0L;
db2 = 0L;

2QFHDGDWDEDVHKDQGOHLVLQLWLDOL]HGWR]HURLWFDQEHXVHGLQDFDOOWRisc_attach_database()
WRHVWDEOLVKDGDWDEDVHFRQQHFWLRQ,IDQRQ]HURGDWDEDVHKDQGOHLVSDVVHGWR
isc_attach_database()WKHFRQQHFWLRQIDLOVDQGDQHUURUFRGHLVUHWXUQHG)RUPRUH
LQIRUPDWLRQDERXWHVWDEOLVKLQJDGDWDEDVHFRQQHFWLRQZLWKisc_attach_database()VHH
´$WWDFKLQJWRDGDWDEDVHµRQSDJH 

API GUIDE 27
 CHAPTER 4 WORKING WITH DATABASES

Creating and populating a DPB

'DWDEDVHDWWDFKPHQWVFDQRSWLRQDOO\EHWDLORUHGLQPDQ\ZD\VE\FUHDWLQJDGDWDEDVH
SDUDPHWHUEXIIHU '3% SRSXODWLQJLWZLWKGHVLUHGGDWDEDVHFKDUDFWHULVWLFVDQGSDVVLQJWKH
DGGUHVVRIWKH'3%WRisc_attach_database()
)RUH[DPSOHWKH'3%FDQFRQWDLQDXVHUQDPHDQGSDVVZRUGIRUDWWDFKLQJWRDGDWDEDVHRQ
DUHPRWHVHUYHUDQGLWPLJKWDOVRFRQWDLQDSDUDPHWHUWKDWDFWLYDWHVDGDWDEDVHVKDGRZILOH
)RUDOLVWRIDOOSRVVLEOH'3%SDUDPHWHUVVHH7DEOH´'3%SDUDPHWHUVµRQSDJH
8VXDOO\DVHSDUDWH'3%LVFUHDWHGIRUHDFKGDWDEDVHDWWDFKPHQWEXWLIGLIIHUHQWDWWDFKPHQWV
XVHWKHVDPHVHWRISDUDPHWHUVWKH\FDQVKDUHD'3%,ID'3%LVQRWFUHDWHGRULVQRWSDVVHG
WRisc_attach_database()WKHGDWDEDVHDWWDFKPHQWXVHVDGHIDXOWVHWRISDUDPHWHUV

7,3 6RPHRIWKH'3%SDUDPHWHUVFRUUHVSRQGGLUHFWO\WRJIL[RSWLRQV,QIDFWWKDW·VKRZJIL[LV
LPSOHPHQWHGLWVHWVFHUWDLQ'3%SDUDPHWHUVDQGDWWDFKHVWRDGDWDEDVHZKHUHLWSHUIRUPV
WKHUHTXHVWHGRSHUDWLRQ VZHHSVHWDV\QFZULWHVVKXWGRZQRUZKDWHYHU 
$'3%LVDFKDUDUUD\YDULDEOHVSHFLILFDOO\GHFODUHGLQDQDSSOLFDWLRQWKDWFRQVLVWVRIWKH
IROORZLQJSDUWV
 $E\WHVSHFLI\LQJWKHYHUVLRQRIWKHSDUDPHWHUEXIIHUDOZD\VWKHFRPSLOHWLPH
FRQVWDQWLVFBGSEBYHUVLRQ
 $FRQWLJXRXVVHULHVRIRQHRUPRUHFOXVWHUVRIE\WHVHDFKGHVFULELQJDVLQJOH
SDUDPHWHU
(DFKFOXVWHUFRQVLVWVRIWKHIROORZLQJSDUWV
 $RQHE\WHSDUDPHWHUW\SH7KHUHDUHFRPSLOHWLPHFRQVWDQWVGHILQHGIRUDOOWKH
SDUDPHWHUW\SHV IRUH[DPSOHLVFBGSEBQXPBEXIIHUV 
 $RQHE\WHQXPEHUVSHFLI\LQJWKHQXPEHURIE\WHVWKDWIROORZLQWKHUHPDLQGHU
RIWKHFOXVWHU
 $YDULDEOHQXPEHURIE\WHVZKRVHLQWHUSUHWDWLRQ IRUH[DPSOHDVDQXPEHURU
DVDVWULQJRIFKDUDFWHUV GHSHQGVRQWKHSDUDPHWHUW\SH
)RUH[DPSOHWKHIROORZLQJFRGHFUHDWHVD'3%ZLWKDVLQJOHSDUDPHWHUWKDWVHWVWKHQXPEHU
RIFDFKHEXIIHUVWRXVHZKHQFRQQHFWLQJWRDGDWDEDVH
char dpb_buffer[256], *dpb, *p;
short dpb_length;
/* Construct the database parameter buffer. */
dpb = dpb_buffer;
*dpb++ = isc_dpb_version1;
*dpb++ = isc_num_buffers;
*dpb++ = 1;

28 INTERBASE 5
CONNECTING TO DATABASES

*dpb++ = 90;
dpb_length = dpb - dpb_buffer;

,03257$17 $OOQXPEHUVLQWKHGDWDEDVHSDUDPHWHUEXIIHUPXVWEHUHSUHVHQWHGLQDJHQHULFIRUPDWZLWK
WKHOHDVWVLJQLILFDQWE\WHILUVWDQGWKHPRVWVLJQLILFDQWE\WHODVW6LJQHGQXPEHUVVKRXOGKDYH
WKHVLJQLQWKHODVWE\WH7KH$3,IXQFWLRQisc_vax_integer()FDQEHXVHGWRUHYHUVHWKH
E\WHRUGHURIDQXPEHU)RUPRUHLQIRUPDWLRQVHH´LVFBYD[BLQWHJHU µRQSDJH 
7KHIROORZLQJWDEOHOLVWV'3%LWHPVE\SXUSRVH

User validation
User name isc_dpb_user_name
Password isc_dpb_password
Encrypted password isc_dpb_password_enc
Role name isc_dpb_sql_role_name
System database administrator’s user name isc_dpb_sys_user_name
Authorization key for a software license isc_dpb_license
Database encryption key isc_dpb_encrypt_key
Environmental control
Number of cache buffers isc_dpb_num_buffers
dbkey context scope isc_dpb_dbkey_scope
System management
Force writes to the database to be done asynchronously or synchronously isc_dpb_force_write
Specify whether or not to reserve a small amount of space on each database isc_dpb_no_reserve
page for holding backup versions of records when modifications are made
System management
Specify whether or not the database should be marked as damaged isc_dpb_damaged
Perform consistency checking of internal structures isc_dpb_verify
Shadow control
Activate the database shadow, an optional, duplicate, in-sync copy of the isc_dpb_activate_shado
database w
TABLE 4.2 DPB parameters

API GUIDE 29
 CHAPTER 4 WORKING WITH DATABASES

Delete the database shadow isc_dpb_delete_shadow

Replay logging system control
Activate a replay logging system to keep track of all database calls isc_dpb_begin_log
Deactivate the replay logging system isc_dpb_quit_log
Character set and message file specification
Language-specific message file isc_dpb_lc_messages
Character set to be utilized isc_dpb_lc_ctype
TABLE 4.2 DPB parameters (continued)

7KHIROORZLQJWDEOHOLVWV'3%SDUDPHWHUVLQDOSKDEHWLFDORUGHU)RUHDFKSDUDPHWHULWOLVWVLWV
SXUSRVHWKHOHQJWKLQE\WHVRIDQ\YDOXHVSDVVHGZLWKWKHSDUDPHWHUDQGWKHYDOXHWRSDVV

Parameter Purpose Length Value

isc_dpb_activate_shado Directive to activate the database shadow, which is 1 (Ignored) 0 (Ignored)
w an optional, duplicate, in-sync copy of the database
isc_dpb_damaged Number signifying whether or not the database 1 0 or 1
should be marked as damaged
1 = mark as damaged
0 = do not mark as damaged
isc_dpb_dbkey_scope Scope of dbkey context. 0 limits scope to the current 1 0 or 1
transaction, 1 extends scope to the database session
isc_dpb_delete_shadow Directive to delete a database shadow that is no 1(Ignored) 0 (Ignored)
longer needed
isc_dpb_encrypt_key String encryption key, up to 255 characters Number of bytes String containing key
in string
isc_dpb_force_write Specifies whether database writes 1 0 or 1
are synchronous or asynchronous.
0 = asynchronous; 1 = synchronous
isc_dpb_lc_ctype String specifying the character set to be utilized Number of bytes String containing
in string character set name
TABLE 4.3 Alphabetical list of DPB parameters

30 INTERBASE 5
CONNECTING TO DATABASES

Parameter Purpose Length Value

isc_dpb_lc_messages String specifying a language-specific message file Number of bytes String containing
in string message file name
isc_dpb_license String authorization key for a software license Number of bytes String containing key
in string
isc_dpb_no_reserve Specifies whether or not a small amount of space on 1 0 or 1
each database page is reserved for holding backup
versions of records when modifications are made;
keep backup versions on the same page as the
primary record to optimize update activity
0 (default) = reserve space
1= do not reserve space
isc_dpb_num_buffers Number of database cache buffers to allocate for use 1 Number of buffers to
with the database; default=75 allocate
isc_dpb_password String password, up to 255 characters Number of bytes String containing
in string password
isc_dpb_password_enc String encrypted password, up to 255 characters Number of bytes in String containing
string password
isc_dpb_sys_user_name String system DBA name, up to 255 characters Number of bytes in String containing
string SYSDBA name
isc_dpb_user_name String user name, up to 255 characters Number of bytes in String containing user
string name
TABLE 4.3 Alphabetical list of DPB parameters (continued)

Note 6RPHSDUDPHWHUVVXFKDVLVFBGSEBGHOHWHBVKDGRZDUHGLUHFWLYHVWKDWGRQRWUHTXLUH
DGGLWLRQDOSDUDPHWHUV(YHQVR\RXPXVWVWLOOSURYLGHOHQJWKDQGYDOXHE\WHVIRUWKHVH
SDUDPHWHUV6HWOHQJWKWRDQGYDOXHWR,QWHU%DVHLJQRUHVWKHVHSDUDPHWHUYDOXHVEXWWKH\
DUHUHTXLUHGWRPDLQWDLQWKHIRUPDWRIWKH'3%

API GUIDE 31
 CHAPTER 4 WORKING WITH DATABASES

Adding parameters to a DPB

6RPHWLPHVLWLVXVHIXOWRDGGSDUDPHWHUVWRDQH[LVWLQJ'3%DWUXQWLPH)RUH[DPSOHZKHQ
DQDSSOLFDWLRQUXQVLWPLJKWGHWHUPLQHDXVHU·VQDPHDQGSDVVZRUGDQGVXSSO\WKRVHYDOXHV
G\QDPLFDOO\7KHisc_expand_dpb()IXQFWLRQFDQEHXVHGWRSDVVWKHIROORZLQJDGGLWLRQDO
SDUDPHWHUVWRDSUHYLRXVO\FUHDWHGDQGSRSXODWHG'3%DWUXQWLPH

Parameter Purpose
isc_dpb_user_name String user name, up to 255 characters
isc_dpb_password String password, up to 255 characters
isc_dpb_lc_messages String specifying a language-specific message file
isc_dpb_lc_ctype String specifying the character set to be utilized
TABLE 4.4 DPB parameters recognized by isc_expand_dpb()

,03257$17 ,I\RXH[SHFWWRDGGDQ\RIWKHVHSDUDPHWHUVDWUXQWLPHWKHQFUHDWHDODUJHUWKDQQHFHVVDU\
'3%EHIRUHFDOOLQJisc_expand_dpb()VRWKDWWKLVIXQFWLRQGRHVQRWQHHGWRUHDOORFDWH
'3%VWRUDJHVSDFHDWUXQWLPHisc_expand_dbp()FDQUHDOORFDWHVSDFHEXWWKDWVSDFHLV
QRWDXWRPDWLFDOO\IUHHGZKHQWKHGDWDEDVHLVGHWDFKHG
isc_expand_dpb()UHTXLUHVWKHIROORZLQJSDUDPHWHUV

Parameter Type Description

dpb char ** Pointer to a DPB
dpb_size unsigned short * Pointer to the current size, in bytes, of the DPB
… char * Pointers to item type and items to add to the DPB
TABLE 4.5 isc_expand_dbp() parameters

7KHWKLUGSDUDPHWHULQWKHWDEOH«LQGLFDWHVDYDULDEOHQXPEHURIUHSODFHDEOHSDUDPHWHUV
HDFKZLWKGLIIHUHQWQDPHVEXWHDFKDFKDUDFWHUSRLQWHU
7KHIROORZLQJFRGHGHPRQVWUDWHVKRZisc_expand_dpb()LVFDOOHGWRDGGDXVHUQDPHDQG
SDVVZRUGWRWKH'3%DIWHUWKH\DUHHOLFLWHGIURPDXVHUDWUXQWLPH
char dpb_buffer[256], *dpb, *p;
char uname[256], upass[256];
short dpb_length;

/* Construct a database parameter buffer. */

32 INTERBASE 5
CONNECTING TO DATABASES

dpb = dpb_buffer;
*dpb++ = isc_dpb_version1;
*dpb++ = isc_num_buffers;
*dpb++ = 1;
*dpb++ = 90;
dpb_length = dpb - dpb_buffer;
/* Now ask user for name and password. */
prompt_user("Enter your user name: ");
gets(uname);
prompt_user("\nEnter your password: ");
gets(upass);
/* Add user name and password to DPB. */
dpb = dbp_buffer;
isc_expand_dpb(&dpb, &dpb_length,
isc_dpb_user_name, uname,
isc_dpb_password, upass,
NULL);

Attaching to a database
$IWHUFUHDWLQJDQGLQLWLDOL]LQJDGDWDEDVHKDQGOHDQGRSWLRQDOO\VHWWLQJXSD'3%WRVSHFLI\
FRQQHFWLRQSDUDPHWHUVXVHisc_attach_database()WRHVWDEOLVKDFRQQHFWLRQWRDQH[LVWLQJ
GDWDEDVH%HVLGHVDOORFDWLQJV\VWHPUHVRXUFHVIRUWKHGDWDEDVHFRQQHFWLRQ
isc_attach_database()DOVRDVVRFLDWHVDVSHFLILFGDWDEDVHZLWKDGDWDEDVHKDQGOHIRUXVHLQ
VXEVHTXHQW$3,FDOOVWKDWUHTXLUHDKDQGOH
isc_attach_database()H[SHFWVVL[SDUDPHWHUV
g $SRLQWHUWRDQHUURUVWDWXVDUUD\ZKHUHDWWDFKPHQWHUURUVFDQEHUHSRUWHGVKRXOGWKH\RFFXU
g 7KHOHQJWKLQE\WHVRIWKHGDWDEDVHQDPHIRUWKHGDWDEDVHWRRSHQ,IWKHGDWDEDVHQDPH
LQFOXGHVDQRGHQDPHDQGSDWKWKHVHHOHPHQWVPXVWEHFRXQWHGLQWKHOHQJWKDUJXPHQW
g $VWULQJFRQWDLQLQJWKHQDPHRIWKHGDWDEDVHWRDWWDFK7KHQDPHFDQLQFOXGHDQRGHQDPH
DQGSDWKVSHFLILFDWLRQ
g $SRLQWHUWRDSUHYLRXVO\GHFODUHGDQGLQLWLDOL]HGGDWDEDVHKDQGOHZLWKZKLFKWRDVVRFLDWHWKH
GDWDEDVHWRDWWDFK$OOVXEVHTXHQW$3,FDOOVXVHWKHKDQGOHWRVSHFLI\DFFHVVWRWKLVGDWDEDVH
g 7KHOHQJWKLQE\WHVRIWKH'3%,IQR'3%LVSDVVHGVHWWKLVYDOXHWR]HUR
g $SRLQWHUWRWKH'3%,IQR'3%LVSDVVHGVHWWKLVWR18//
(DFKGDWDEDVHDWWDFKPHQWUHTXLUHVDVHSDUDWHFDOOWRisc_attach_database()

API GUIDE 33
 CHAPTER 4 WORKING WITH DATABASES

7KHIROORZLQJFRGHHVWDEOLVKHVDQDWWDFKPHQWWRWKH,QWHU%DVHH[DPSOHGDWDEDVHHPSOR\HHJGE
DQGVSHFLILHVD'3%WRXVHIRUWKHDWWDFKPHQW
#include <ibase.h>
. . .
isc_db_handle db1;
char dpb_buffer[256], *dpb, *p;
short dpb_length;
char *str = "employee.gdb";
ISC_STATUS status_vector[20];
. . .
/* Set database handle to zero before attaching to a database. */
db1 = 0L;
/* Initialize the DPB. */
dpb = dpb_buffer;
*dpb++ = isc_dpb_version1;
*dpb++ = isc_num_buffers;
*dpb++ = 1;
*dpb++ = 90;
dpb_length = dpb - dpb_buffer;
/* Attach to the database. */
isc_attach_database(status_vector, strlen(str), str, &db1, dpb_length,
dbp_buffer);
if (status_vector[0] == 1 && status_vector[1])
{
error_exit();
}
. . .

7KHIROORZLQJFRGHLOOXVWUDWHVKRZWRDWWDFKWRDGDWDEDVHZLWKRXWSDVVLQJD'3%
#include <ibase.h>
. . .
isc_db_handle db1;
char *str = "employee.gdb";
ISC_STATUS status_vector[20];
. . .
/* Set database handle to zero before attaching to a database. */
db1 = 0L;
/* Attach to the database. */
isc_attach_database(status_vector, strlen(str), str, &db1, 0, NULL);
if (status_vector[0] == 1 && status_vector[1])
{
error_exit();
}

34 INTERBASE 5
REQUESTING INFORMATION ABOUT AN ATTACHMENT

. . .

Requesting information about an attachment

$IWHUDQDSSOLFDWLRQDWWDFKHVWRDGDWDEDVHLWPD\QHHGLQIRUPDWLRQDERXWWKHDWWDFKPHQW
7KHisc_database_info()FDOOHQDEOHVDQDSSOLFDWLRQWRTXHU\IRUDWWDFKPHQWLQIRUPDWLRQ
VXFKDVWKHYHUVLRQRIWKHRQGLVNVWUXFWXUH 2'6 XVHGE\WKHDWWDFKPHQWWKHQXPEHURI
GDWDEDVHFDFKHEXIIHUVDOORFDWHGWKHQXPEHURIGDWDEDVHVSDJHVUHDGIURPRUZULWWHQWRRU
ZULWHDKHDGORJLQIRUPDWLRQ
,QDGGLWLRQWRDSRLQWHUWRWKHHUURUVWDWXVYHFWRUDQGDGDWDEDVHKDQGOH
isc_database_info()UHTXLUHVWZRDSSOLFDWLRQSURYLGHGEXIIHUVDUHTXHVWEXIIHUZKHUHWKH
DSSOLFDWLRQVSHFLILHVWKHLQIRUPDWLRQLWQHHGVDQGDUHVXOWEXIIHUZKHUH,QWHU%DVHUHWXUQVWKH
UHTXHVWHGLQIRUPDWLRQ$QDSSOLFDWLRQSRSXODWHVWKHUHTXHVWEXIIHUZLWKLQIRUPDWLRQSULRU
WRFDOOLQJisc_database_info()DQGSDVVHVLWERWKDSRLQWHUWRWKHUHTXHVWEXIIHUDQGWKH
VL]HLQE\WHVRIWKDWEXIIHU
7KHDSSOLFDWLRQPXVWDOVRFUHDWHDUHVXOWEXIIHUODUJHHQRXJKWRKROGWKHLQIRUPDWLRQ
UHWXUQHGE\,QWHU%DVH,WSDVVHVERWKDSRLQWHUWRWKHUHVXOWEXIIHUDQGWKHVL]HLQE\WHVRI
WKDWEXIIHUWRisc_database_info(),I,QWHU%DVHDWWHPSWVWRSDVVEDFNPRUHLQIRUPDWLRQ
WKDQFDQILWLQWKHUHVXOWEXIIHULWSXWVWKHYDOXHLVFBLQIRBWUXQFDWHGGHILQHGLQLEDVHKLQWKH
ILQDOE\WHRIWKHUHVXOWEXIIHU

Requesting buffer items and result buffer values

7KHUHTXHVWEXIIHULVDFKDUDUUD\LQWRZKLFKLVSODFHGDVHTXHQFHRIE\WHYDOXHVRQHSHU
UHTXHVWHGLWHPRILQIRUPDWLRQ(DFKE\WHLVDQLWHPW\SHVSHFLI\LQJWKHNLQGRILQIRUPDWLRQ
GHVLUHG&RPSLOHWLPHFRQVWDQWVIRUDOOLWHPW\SHVDUHGHILQHGLQLEDVHK
7KHUHVXOWEXIIHUUHWXUQVDVHULHVRIFOXVWHUVRILQIRUPDWLRQRQHSHULWHPUHTXHVWHG(DFK
FOXVWHUFRQVLVWVRIWKUHHSDUWV
 $RQHE\WHLWHPUHWXUQW\SH7KHUHDUHFRPSLOHWLPHFRQVWDQWVGHILQHGIRUDOOWKH
LWHPUHWXUQW\SHVLQLEDVHK
 $WZRE\WHQXPEHUVSHFLI\LQJWKHQXPEHURIE\WHVWKDWIROORZLQWKHUHPDLQGHU
RIWKHFOXVWHU
 $YDOXHVWRUHGLQDYDULDEOHQXPEHURIE\WHVZKRVHLQWHUSUHWDWLRQ IRUH[DPSOH
DVDQXPEHURUDVDVWULQJRIFKDUDFWHUV GHSHQGVRQWKHLWHPUHWXUQW\SH

API GUIDE 35
 CHAPTER 4 WORKING WITH DATABASES

$FDOOLQJSURJUDPLVUHVSRQVLEOHIRULQWHUSUHWLQJWKHFRQWHQWVRIWKHUHVXOWEXIIHUDQGIRU
GHFLSKHULQJHDFKFOXVWHUDVDSSURSULDWH,QPDQ\FDVHVWKHYDOXHVLPSO\FRQWDLQVDQXPEHU
RUDVWULQJ VHTXHQFHRIFKDUDFWHUV %XWLQRWKHUFDVHVWKHYDOXHLVDQXPEHURIE\WHVZKRVH
LQWHUSUHWDWLRQGHSHQGVRQWKHLWHPUHWXUQW\SH
7KHFOXVWHUVUHWXUQHGWRWKHUHVXOWEXIIHUDUHQRWDOLJQHG)XUWKHUPRUHDOOQXPEHUVDUH
UHSUHVHQWHGLQDJHQHULFIRUPDWZLWKWKHOHDVWVLJQLILFDQWE\WHILUVWDQGWKHPRVWVLJQLILFDQW
E\WHODVW6LJQHGQXPEHUVKDYHWKHVLJQLQWKHODVWE\WH&RQYHUWWKHQXPEHUVWRDGDWDW\SH
QDWLYHWR\RXUV\VWHPLIQHFHVVDU\EHIRUHLQWHUSUHWLQJWKHP7KH$3,FDOO
isc_vax_integer()FDQEHXVHGWRSHUIRUPWKHFRQYHUVLRQ

4 'DWDEDVHFKDUDFWHULVWLFV
6HYHUDOLWHPVDUHDYDLODEOHIRUGHWHUPLQLQJGDWDEDVHFKDUDFWHULVWLFVVXFKDVLWVVL]HDQGPDMRU
DQGPLQRU2'6YHUVLRQQXPEHUV7KHIROORZLQJWDEOHOLVWVWKHUHTXHVWEXIIHULWHPVWKDWFDQ
EHSDVVHGDQGWKHLQIRUPDWLRQUHWXUQHGLQWKHUHVXOWEXIIHUIRUHDFKLWHPW\SH

Request buffer item Result buffer contents

isc_info_allocation Number of database pages allocated
isc_info_base_level Database version (level) number:
• 1 byte containing the number 1
• 1 byte containing the version number
isc_info_db_id • Database file name and site name:
• 1 byte containing the number 2 for a local connection or 4 for a remote
connection
• 1 byte containing the length, d, of the database file name in bytes
• A string of d bytes, containing the database file name
• 1 byte containing the length, l, of the site name in bytes
• A string of l bytes, containing the site name
isc_info_implementation Database implementation number:
• 1 byte containing a 1
• 1 byte containing the implementation number
• 1 byte containing a “class” number, either 1 or 12
TABLE 4.6 Database information items for database characteristics

36 INTERBASE 5
REQUESTING INFORMATION ABOUT AN ATTACHMENT

Request buffer item Result buffer contents

isc_info_no_reserve 0 or 1
• 0 indicates space is reserved on each database page for holding backup
versions of modified records [Default]
• 1 indicates no space is reserved for such records
isc_info_ods_minor_version On-disk structure (ODS) minor version number; an increase in a minor
version number indicates a non-structural change, one that still allows the
database to be accessed by database engines with the same major version
number but possibly different minor version numbers
isc_info_ods_version ODS major version number; databases with different major version
numbers have different physical layouts
A database engine can access only databases with a particular ODS major
version number; trying to attach to a database with a different ODS
number results in an error
isc_info_page_size Number of bytes per page of the attached database; use with
isc_info_allocation to determine the size of the database
isc_info_version Version identification string of the database implementation:
• 1 byte containing the number 1
• 1 byte specifying the length, n, of the following string
• n bytes containing the version identification string
TABLE 4.6 Database information items for database characteristics (continued)

4 (QYLURQPHQWDOFKDUDFWHULVWLFV
6HYHUDOLWHPVDUHSURYLGHGIRUGHWHUPLQLQJHQYLURQPHQWDOFKDUDFWHULVWLFVVXFKDV
WKHDPRXQWRIPHPRU\FXUUHQWO\LQXVHRUWKHQXPEHURIGDWDEDVHFDFKHEXIIHUVFXUUHQWO\
DOORFDWHG7KHVHLWHPVDUHGHVFULEHGLQWKHIROORZLQJWDEOH

Request buffer item Result buffer contents

isc_info_current_memory Amount of server memory (in bytes) currently in use
isc_info_forced_writes Number specifying the mode in which database writes are performed (0 for
asynchronous, 1 for synchronous)
isc_info_max_memory Maximum amount of memory (in bytes) used at one time since the first
process attached to the database
TABLE 4.7 Database information items for environmental characteristics

API GUIDE 37
 CHAPTER 4 WORKING WITH DATABASES

Request buffer item Result buffer contents

isc_info_num_buffers Number of memory buffers currently allocated
isc_info_sweep_interval Number of transactions that are committed between “sweeps” to remove
database record versions that are no longer needed
isc_info_user_names Names of all the users currently attached to the database; for each such user,
the result buffer contains an isc_info_user_names byte followed by a 1-byte
length specifying the number of bytes in the user name, followed by the user
name
TABLE 4.7 Database information items for environmental characteristics (continued)

Note 1RWDOOHQYLURQPHQWDOLQIRUPDWLRQLWHPVDUHDYDLODEOHRQDOOSODWIRUPV

4 3HUIRUPDQFHVWDWLVWLFV
7KHUHDUHIRXULWHPVWKDWUHTXHVWSHUIRUPDQFHVWDWLVWLFVIRUDGDWDEDVH7KHVHVWDWLVWLFV
DFFXPXODWHIRUDGDWDEDVHIURPWKHPRPHQWLWLVILUVWDWWDFKHGE\DQ\SURFHVVXQWLOWKHODVW
UHPDLQLQJSURFHVVGHWDFKHVIURPWKHGDWDEDVH
)RUH[DPSOHWKHYDOXHUHWXUQHGIRULVFBLQIRBUHDGVLVWKHQXPEHURIUHDGVVLQFHWKHFXUUHQW
GDWDEDVHZDVILUVWDWWDFKHGWKDWLVDQDJJUHJDWHRIDOOUHDGVGRQHE\DOODWWDFKHGSURFHVVHV
UDWKHUWKDQWKHQXPEHURIUHDGVGRQHIRUWKHFDOOLQJSURJUDPVLQFHLWDWWDFKHGWRWKHGDWDEDVH
7DEOHOLVWVWKHUHTXHVWSHUIRUPDQFHVWDWLVWLFVDUHVXPPDUL]HGLQWKHIROORZLQJWDEOH

Request buffer item Result buffer contents

isc_info_fetches Number of reads from the memory buffer cache
isc_info_marks Number of writes to the memory buffer cache
isc_info_reads Number of page reads
isc_info_writes Number of page writes
TABLE 4.8 Database information items for performance statistics

4 'DWDEDVHRSHUDWLRQFRXQWV
6HYHUDOLQIRUPDWLRQLWHPVDUHSURYLGHGIRUGHWHUPLQLQJWKHQXPEHURIYDULRXVGDWDEDVH
RSHUDWLRQVSHUIRUPHGE\WKHFXUUHQWO\DWWDFKHGFDOOLQJSURJUDP7KHVHYDOXHVDUHFDOFXODWHG
RQDSHUWDEOHEDVLV
:KHQDQ\RIWKHVHLQIRUPDWLRQLWHPVLVUHTXHVWHG,QWHU%DVHUHWXUQVWRWKHUHVXOWEXIIHU
g E\WHVSHFLI\LQJWKHLWHPW\SH IRUH[DPSOHLVFBLQIRBLQVHUWBFRXQW 

38 INTERBASE 5
REQUESTING INFORMATION ABOUT AN ATTACHMENT

g E\WHVWHOOLQJKRZPDQ\E\WHVFRPSRVHWKHVXEVHTXHQWYDOXHSDLUV
g $SDLURIYDOXHVIRUHDFKWDEOHLQWKHGDWDEDVHRQZKLFKWKHUHTXHVWHGW\SHRIRSHUDWLRQKDV
RFFXUUHGVLQFHWKHGDWDEDVHZDVODVWDWWDFKHG
(DFKSDLUFRQVLVWVRI
g E\WHVVSHFLI\LQJWKHWDEOH,'
g E\WHVOLVWLQJWKHQXPEHURIRSHUDWLRQV IRUH[DPSOHLQVHUWV GRQHRQWKDWWDEOH

7,3 7RGHWHUPLQHDQDFWXDOWDEOHQDPHIURPDWDEOH,'TXHU\WKHV\VWHPWDEOH5'%5(/$7,21
7KHIROORZLQJWDEOHGHVFULEHVWKHLWHPVZKLFKUHWXUQFRXQWYDOXHVIRURSHUDWLRQVRQWKH
GDWDEDVH

Request buffer item Result buffer contents

isc_info_backout_count Number of removals of a version of a record
isc_info_delete_count Number of database deletes since the database was last attached
isc_info_expunge_count Number of removals of a record and all of its ancestors, for records whose
deletions have been committed
isc_info_insert_count Number of inserts into the database since the database was last attached
isc_info_purge_count Number of removals of old versions of fully mature records (records
committed, resulting in older—ancestor—versions no longer being
needed)
isc_info_read_idx_count Number of reads done via an index since the database was last attached
isc_info_read_seq_count Number of sequential database reads, that is, the number of sequential
table scans (row reads) done on each table since the database was last
attached
isc_info_update_count Number of database updates since the database was last attached
TABLE 4.9 Database information items for operation counts

isc_database_info() call example

7KHIROORZLQJFRGHUHTXHVWVWKHSDJHVL]HDQGWKHQXPEHURIEXIIHUVIRUWKHFXUUHQWO\
DWWDFKHGGDWDEDVHWKHQH[DPLQHVWKHUHVXOWEXIIHU
char db_items[] = {
isc_info_page_size, isc_info_num_buffers,

API GUIDE 39
 CHAPTER 4 WORKING WITH DATABASES

isc_info_end};
char res_buffer[40], *p, item;
int length;
SLONG page_size = 0L, num_buffers = 0L;
ISC_STATUS status_vector[20];

isc_database_info(
status_vector,
&handle, /* Set in previous isc_attach_database() call. */
sizeof(db_items),
db_items,
sizeof(res_buffer),
res_buffer);
if (status_vector[0] == 1 && status_vector[1]) {
/* An error occurred. */
isc_print_status(status_vector);
return(1);
};
/* Extract the values returned in the result buffer. */
for (p = res_buffer; *p != isc_info_end ; ) {
item = *p++
length = isc_vax_integer(p, 2);
p += 2;
switch (item){
case isc_info_page_size:
page_size = isc_vax_integer(p, length);
break;
case isc_info_num_buffers:
num_buffers = isc_vax_integer(p, length);
break;
default:
break;
}
p += length;
};

40 INTERBASE 5
DISCONNECTING FROM DATABASES

Disconnecting from databases

:KHQDQDSSOLFDWLRQLVILQLVKHGDFFHVVLQJDGDWDEDVHDQGDQ\FKDQJHVDUHFRPPLWWHGRU
UROOHGEDFNWKHDSSOLFDWLRQVKRXOGGLVFRQQHFWIURPWKHGDWDEDVHUHOHDVHV\VWHPUHVRXUFHV
DOORFDWHGIRUWKHDWWDFKPHQWDQGVHWWKHGDWDEDVHKDQGOHWR]HURZLWKDFDOOWR
isc_detach_database()
isc_detach_database()UHTXLUHVWZRDUJXPHQWVDSRLQWHUWRWKHHUURUVWDWXVYHFWRUDQGD
SRLQWHUWRWKHKDQGOHRIWKHGDWDEDVHIURPZKLFKWRGHWDFK)RUH[DPSOHWKHIROORZLQJ
VWDWHPHQWGHWDFKHVIURPWKHGDWDEDVHSRLQWHGWRE\WKHGDWDEDVHKDQGOHGE
isc_detach_database(status_vector, &db1);

(DFKGDWDEDVHWRGHWDFKUHTXLUHVDVHSDUDWHFDOOWRisc_detach_database()

Deleting a database
7RUHPRYHDGDWDEDVHIURPWKHV\VWHPLILWLVQRORQJHUQHHGHGXVHisc_drop_database()
7KLVIXQFWLRQSHUPDQHQWO\ZLSHVRXWDGDWDEDVHHUDVLQJLWVGDWDPHWDGDWDDQGDOORILWV
VXSSRUWLQJILOHVVXFKDVVHFRQGDU\ILOHVVKDGRZILOHVDQGZULWHDKHDGORJILOHV
$GDWDEDVHFDQRQO\EHGHOHWHGLILWLVSUHYLRXVO\DWWDFKHGZLWKDFDOOWR
isc_attach_database()7KHFDOOWRisc_attach_database()HVWDEOLVKHVDGDWDEDVHKDQGOH
IRUWKHGDWDEDVH7KDWKDQGOHPXVWEHSDVVHGLQWKHFDOOWRisc_drop_database()
)RUH[DPSOHWKHIROORZLQJFRGHGHOHWHVWKHGDWDEDVHSRLQWHGWRE\WKHGDWDEDVHKDQGOHGE
#include <ibase.h>
. . .
isc_db_handle db1;
char *str = "employee.gdb";
ISC_STATUS status_vector[20];
. . .
/* Set database handle to zero before attaching to a database. */
db1 = 0L;
/* Attach to the database. */
isc_attach_database(status_vector, strlen(str), str, &db1, 0, NULL);
if (status_vector[0] == 1 && status_vector[1])
{
error_exit();
}
isc_drop_database(status_vector, &db1);
if (status_vector[0] == 1 && status_vector[1])
{

API GUIDE 41
 CHAPTER 4 WORKING WITH DATABASES

error_exit();
}
. . .

42 INTERBASE 5
 CHAPTER

Working with Transactions

Chapter5
5
7KLVFKDSWHUGHVFULEHVKRZWRVHWXSDWUDQVDFWLRQSDUDPHWHUEXIIHU 73% WKDWFRQWDLQV
SDUDPHWHUVKRZWRVHWXSDQGLQLWLDOL]HWUDQVDFWLRQKDQGOHVDQGKRZWRXVHWKH$3,IXQFWLRQV
WKDWFRQWUROWUDQVDFWLRQV,WDOVRH[SODLQVKRZWRUHWULHYHDWUDQVDFWLRQ,'
$OOGDWDGHILQLWLRQDQGGDWDPDQLSXODWLRQLQDQDSSOLFDWLRQWDNHVSODFHLQWKHFRQWH[WRIRQH
RUPRUHWUDQVDFWLRQVRQHRUPRUHVWDWHPHQWVWKDWZRUNWRJHWKHUWRFRPSOHWHDVSHFLILFVHWRI
DFWLRQVWKDWPXVWEHWUHDWHGDVDQDWRPLFXQLWRIZRUN
7KHIROORZLQJWDEOHVXPPDUL]HVWKH$3,IXQFWLRQVPRVWFRPPRQO\XVHGZKHQZRUNLQJZLWK
WUDQVDFWLRQV)XQFWLRQVDUHOLVWHGLQWKHRUGHUWKH\W\SLFDOO\DSSHDULQDQDSSOLFDWLRQ

Function Purpose
isc_start_transaction() Starts a new transaction against one or more databases.; use a
previously declared and populated TPB
isc_commit_retaining() Commits a transaction’s changes, and preserves the transaction
context for further transaction processing
isc_commit_transaction() Commits a transaction’s changes, and ends the transaction
isc_rollback_transaction() Rolls back a transaction’s changes, and ends the transaction
TABLE 5.1 API transaction functions

43
 CHAPTER 5 WORKING WITH TRANSACTIONS

,QDGGLWLRQWRWKHVHIXQFWLRQVWKHIROORZLQJWDEOHOLVWVOHVVIUHTXHQWO\XVHG$3,WUDQVDFWLRQ
IXQFWLRQVLQWKHRUGHUWKH\W\SLFDOO\DSSHDUZKHQXVHG

Function Purpose
isc_start_multiple() Starts a new transaction against one or more databases; used instead of
isc_start_transaction() for programming languages such as
FORTRAN, that do not support variable numbers of arguments to
functions
isc_prepare_transaction() Performs the first phase of a two-phase commit, prior to calling
isc_commit_transaction(); used only when it is absolutely necessary
to override InterBase’s automatic two-phase commit
isc_prepare_transaction2() Performs the first phase of a two-phase commit, prior to calling
isc_commit_transaction(); used only when absolutely necessary to
override InterBase’s automatic two-phase commit
TABLE 5.2 Additional API transaction functions

Starting transactions
6WDUWLQJWUDQVDFWLRQVLVDWKUHHVWHSSURFHVV
 &UHDWLQJDQGLQLWLDOL]LQJDWUDQVDFWLRQKDQGOHIRUHDFKVLPXOWDQHRXVWUDQVDFWLRQ
WREHVWDUWHG
 2SWLRQDOO\FUHDWLQJDQGSRSXODWLQJD73%IRUHDFKWUDQVDFWLRQ
 &DOOLQJisc_start_transaction()IRUHDFKWUDQVDFWLRQWRVWDUW
7KHVHVWHSVDUHGHVFULEHGLQWKHIROORZLQJVHFWLRQVRIWKLVFKDSWHU
Note 3URJUDPPHUVZULWLQJDSSOLFDWLRQVWKDWGRQRWSHUPLWIXQFWLRQFDOOVWRSDVVDYDULDEOH
QXPEHURISDUDPHWHUVPXVWXVHisc_start_multiple()LQVWHDGRIisc_start_transaction()

44 INTERBASE 5
STARTING TRANSACTIONS

Creating transaction handles

(YHU\WUDQVDFWLRQWKDWLVXVHGLQDQDSSOLFDWLRQPXVWEHDVVRFLDWHGZLWKLWVRZQWUDQVDFWLRQ
KDQGOHDSRLQWHUWRDQDGGUHVVWKDWLVXVHGE\DOO$3,WUDQVDFWLRQIXQFWLRQV7KHLEDVHKKHDGHU
ILOHFRQWDLQVWKHIROORZLQJ&W\SHGHIGHFODUDWLRQIRUWUDQVDFWLRQKDQGOHV
typedef void ISC_FAR *isc_tr_handle;

7RXVHWKLVW\SHGHIIRUGHFODULQJWUDQVDFWLRQKDQGOHVLQDQDSSOLFDWLRQLQFOXGHLEDVHKLQHDFK
VRXUFHILOHPRGXOH
#include <ibase.h>

4 'HFODULQJWUDQVDFWLRQKDQGOHV
7RHVWDEOLVKWUDQVDFWLRQKDQGOHVIRUXVHGHFODUHDYDULDEOHRIW\SHLVFBWUBKDQGOHIRUHDFK
VLPXOWDQHRXVO\DFWLYHWUDQVDFWLRQ7KHIROORZLQJFRGHGHFODUHVWZRKDQGOHV
#include <ibase.h>
. . .
isc_tr_handle tr1;
iac_tr_handle tr2;

2QFHDWUDQVDFWLRQLVFRPPLWWHGRUUROOHGEDFNLWVKDQGOHFDQEHDVVLJQHGWRDGLIIHUHQW
WUDQVDFWLRQLQDVXEVHTXHQWFDOOWRisc_start_transaction(),IDQDSSOLFDWLRQXVHVVHYHUDO
WUDQVDFWLRQVEXWRQO\VWDUWVDVXEVHWRIWUDQVDFWLRQVDWWKHVDPHWLPHLWLVRQO\QHFHVVDU\WR
GHFODUHDVPDQ\KDQGOHVDVWKHUHZLOOEHVLPXOWDQHRXVO\DFWLYHWUDQVDFWLRQV)RUH[DPSOHLI
DQDSSOLFDWLRQVWDUWVDWRWDORIWKUHHWUDQVDFWLRQVEXWRQO\UXQVWZRRIWKHPDWWKHVDPHWLPH
RQO\WZRWUDQVDFWLRQKDQGOHVQHHGEHGHFODUHG

4 ,QLWLDOL]LQJWUDQVDFWLRQKDQGOHV
%HIRUHDWUDQVDFWLRQKDQGOHFDQEHXVHGWRVWDUWDQHZWUDQVDFWLRQLWPXVWEHVHWWR]HUR7KH
IROORZLQJFRGHLOOXVWUDWHVKRZWZRWUDQVDFWLRQKDQGOHVDUHVHWWR]HUR
#include <ibase.h>
. . .
isc_tr_handle tr1;
isc_tr_handle tr2;
. . .
/* Set transaction handles to zero before starting a transaction. */
tr1 = 0L;
tr2 = 0L;

API GUIDE 45
 CHAPTER 5 WORKING WITH TRANSACTIONS

2QFHDWUDQVDFWLRQKDQGOHLVLQLWLDOL]HGWR]HURLWFDQEHXVHGLQDFDOOWR
isc_start_transaction()WRHVWDEOLVKDQHZWUDQVDFWLRQ,IDQRQ]HURWUDQVDFWLRQKDQGOHLV
SDVVHGWRisc_start_transaction()WKHVWDUWXSIDLOVDQGDQHUURUFRGHLVUHWXUQHG)RUPRUH
LQIRUPDWLRQDERXWVWDUWLQJDQHZWUDQVDFWLRQZLWKisc_start_transaction()VHH´&DOOLQJ
LVFBVWDUWBWUDQVDFWLRQ  µRQSDJH 

Creating a transaction parameter buffer

7KHWUDQVDFWLRQSDUDPHWHUEXIIHU 73% LVDQRSWLRQDODSSOLFDWLRQGHILQHGE\WHYHFWRUSDVVHGDV
DQDUJXPHQWWRisc_start_transaction()WKDWVHWVXSDWUDQVDFWLRQ·VDWWULEXWHVLWVRSHUDWLQJ
FKDUDFWHULVWLFVVXFKDVZKHWKHUWKHWUDQVDFWLRQKDVUHDGDQGZULWHDFFHVVWRWDEOHVRU
UHDGRQO\DFFHVVDQGZKHWKHURUQRWRWKHUVLPXOWDQHRXVO\DFWLYHWUDQVDFWLRQVFDQVKDUHWDEOH
DFFHVVZLWKWKHWUDQVDFWLRQ(DFKWUDQVDFWLRQPD\KDYHLWVRZQ73%RUWUDQVDFWLRQVWKDW
VKDUHRSHUDWLQJFKDUDFWHULVWLFVFDQXVHWKHVDPH73%
Note ,ID73%LVQRWFUHDWHGIRUDWUDQVDFWLRQD18//SRLQWHUPXVWEHSDVVHGWR
isc_start_transaction()LQLWVSODFH$GHIDXOWVHWRIDWWULEXWHVLVDXWRPDWLFDOO\DVVLJQHGWR
VXFKWUDQVDFWLRQV)RUPRUHLQIRUPDWLRQDERXWWKHGHIDXOW73%VHH´8VLQJWKHGHIDXOW73%µ
RQSDJH 
$73%LVGHFODUHGLQD&SURJUDPDVDFKDUDUUD\RIRQHE\WHHOHPHQWV(DFKHOHPHQWLVD
SDUDPHWHUWKDWGHVFULEHVDVLQJOHWUDQVDFWLRQDWWULEXWH$W\SLFDOGHFODUDWLRQLVDVIROORZV
static char isc_tpb[] = {isc_tpb_version3,
isc_tpb_write,
isc_tpb_read_committed,
isc_tpb_no_rec_version,
isc_tpb_wait};

7KLVH[DPSOHPDNHVXVHRISDUDPHWHUFRQVWDQWVGHILQHGLQWKH,QWHU%DVHKHDGHUILOHLEDVHK
7KHILUVWHOHPHQWLQHYHU\73%PXVWEHWKHLVFBWSEBYHUVLRQFRQVWDQW7KHIROORZLQJWDEOHOLVWV
DYDLODEOH73%FRQVWDQWVGHVFULEHVWKHLUSXUSRVHVDQGLQGLFDWHVZKLFKFRQVWDQWVDUHDVVLJQHG
DVDGHIDXOWVHWRIDWWULEXWHVZKHQD18//73%SRLQWHULVSDVVHGWRisc_start_transaction()

Parameter Description
isc_tpb_version3 InterBase version 3 transaction
isc_tpb_consistency Table-locking transaction model
isc_tpb_concurrency High throughput, high concurrency transaction with acceptable consistency;
use of this parameter takes full advantage of the InterBase multi-generational
transaction model [Default]
TABLE 5.3 TPB constants

46 INTERBASE 5
STARTING TRANSACTIONS

Parameter Description
isc_tpb_shared Concurrent, shared access of a specified table among all transactions; use in
conjunction with isc_tpb_lock_read and isc_tpb_lock_write to establish the
lock option [Default]
isc_tpb_protected Concurrent, restricted access of a specified table; use in conjunction with
isc_tpb_lock_read and isc_tpb_lock_write to establish the lock option
isc_tpb_wait Lock resolution specifies that the transaction is to wait until locked resources
are released before retrying an operation [Default]
isc_tpb_nowait Lock resolution specifies that the transaction is not to wait for locks to be
released, but instead, a lock conflict error should be returned immediately
isc_tpb_read Read-only access mode that allows a transaction only to select data from
tables
isc_tpb_write Read-write access mode of that allows a transaction to select, insert, update,
and delete table data [Default]
isc_tpb_lock_read Read-only access of a specified table. Use in conjunction with isc_tpb_shared,
isc_tpb_protected, and isc_tpb_exclusive to establish the lock option.
isc_tpb_lock_write Read-write access of a specified table. Use in conjunction with
isc_tpb_shared, isc_tpb_protected, and isc_tpb_exclusive to establish the lock
option [Default]
isc_tpb_read_committed High throughput, high concurrency transaction that can read changes
committed by other concurrent transactions. Use of this parameter takes full
advantage of the InterBase
multi-generational transaction model.
isc_tpb_rec_version Enables an isc_tpb_read_committed transaction to read the most recently
committed version of a record even if other, uncommitted versions are
pending.
isc_tpb_no_rec_version Enables an isc_tpb_read_committed transaction to read only the latest
committed version of a record. If an uncommitted version of a record is
pending and isc_tpb_wait is also specified, then the transaction waits for the
pending record to be committed or rolled back before proceeding. Otherwise,
a lock conflict error is reported at once.
TABLE 5.3 TPB constants (continued)

73%SDUDPHWHUVVSHFLI\WKHIROORZLQJFODVVHVRILQIRUPDWLRQ
g 7UDQVDFWLRQYHUVLRQQXPEHULVXVHGLQWHUQDOO\E\WKH,QWHU%DVHHQJLQH,WLVDOZD\VEHWKHILUVW
DWWULEXWHVSHFLILHGLQWKH73%DQGPXVWDOZD\VEHVHWWRLVFBWSEBYHUVLRQ

API GUIDE 47
 CHAPTER 5 WORKING WITH TRANSACTIONS

g $FFHVVPRGHGHVFULEHVWKHDFWLRQVWKDWFDQEHSHUIRUPHGE\WKHIXQFWLRQVDVVRFLDWHGZLWKWKH
WUDQVDFWLRQ9DOLGDFFHVVPRGHVDUH
LVFBWSEBUHDG
LVFBWSEBZULWH
g ,VRODWLRQOHYHOGHVFULEHVWKHYLHZRIWKHGDWDEDVHJLYHQDWUDQVDFWLRQDVLWUHODWHVWRDFWLRQV
SHUIRUPHGE\RWKHUVLPXOWDQHRXVO\RFFXUULQJWUDQVDFWLRQV9DOLGLVRODWLRQOHYHOVDUH
LVFBWSEBFRQFXUUHQF\
LVFBWSEBFRQVLVWHQF\
LVFBWSEBUHDGBFRPPLWWHGLVFBWSEBUHFBYHUVLRQ
LVFBWSEBUHDGBFRPPLWWHGLVFBWSEBQRBUHFBYHUVLRQ
g /RFNUHVROXWLRQGHVFULEHVKRZDWUDQVDFWLRQVKRXOGUHDFWLIDORFNFRQIOLFWRFFXUV9DOLGORFN
UHVROXWLRQVDUH
LVFBWSEBZDLW
LVFBWSEBQRZDLW
g 7DEOHUHVHUYDWLRQRSWLRQDOO\GHVFULEHVDQDFFHVVPHWKRGDQGORFNUHVROXWLRQIRUDVSHFLILHGWDEOH
WKDWWKHWUDQVDFWLRQDFFHVVHV:KHQWDEOHUHVHUYDWLRQLVXVHGWDEOHVDUHUHVHUYHGIRUWKH
VSHFLILHGDFFHVVZKHQWKHWUDQVDFWLRQLVVWDUWHGUDWKHUWKDQZKHQWKHWUDQVDFWLRQDFWXDOO\
DFFHVVHVWKHWDEOH9DOLGUHVHUYDWLRQVDUH
LVFBWSEBVKDUHGLVFBWSEBORFNBZULWH
LVFBWSEBVKDUHGLVFBWSEBORFNBUHDG
LVFBWSEBSURWHFWHGLVFBWSEBORFNBZULWH
LVFBWSEBSURWHFWHGLVFBWSEBORFNBUHDG
73%SDUDPHWHUVDUHGHVFULEHGLQGHWDLOLQWKHIROORZLQJVHFWLRQV

4 6SHFLI\LQJWKHWUDQVDFWLRQYHUVLRQQXPEHU
7KHILUVWSDUDPHWHULQD73%PXVWDOZD\VVSHFLI\WKHYHUVLRQQXPEHUIRUWUDQVDFWLRQ
SURFHVVLQJ,WPXVWDOZD\VEHVHWWRLVFBWSEBYHUVLRQ7KHIROORZLQJ73%GHFODUDWLRQLOOXVWUDWHV
WKHFRUUHFWXVHDQGSRVLWLRQRIWKLVSDUDPHWHU
static char isc_tpb[] = {isc_tpb_version3, ...};

48 INTERBASE 5
STARTING TRANSACTIONS

4 6SHFLI\LQJDFFHVVPRGH
7KHDFFHVVPRGHSDUDPHWHUGHVFULEHVWKHDFWLRQVDWUDQVDFWLRQFDQSHUIRUPDJDLQVWDWDEOH
7KHGHIDXOWDFFHVVPRGHLVFBWSEBZULWHHQDEOHVDWUDQVDFWLRQWRUHDGGDWDIURPDWDEOHDQG
ZULWHGDWDWRLW$VHFRQGDFFHVVPRGHLVFBWSEBUHDGUHVWULFWVWDEOHDFFHVVWRUHDGRQO\)RU
H[DPSOHWKHIROORZLQJ73%GHFODUDWLRQVSHFLILHVDUHDGRQO\WUDQVDFWLRQ
static char isc_tpb[] = {isc_tpb_version3, isc_tpb_read};

$73%VKRXOGRQO\VSHFLI\RQHDFFHVVPRGHSDUDPHWHU,IPRUHWKDQRQHLVVSHFLILHGODWHU
GHFODUDWLRQVRYHUULGHHDUOLHURQHV
,ID73%LVGHFODUHGWKDWRPLWVWKHDFFHVVPRGHSDUDPHWHU,QWHU%DVHLQWHUSUHWVWUDQVDFWLRQ
DFFHVVDVUHDGDQGZULWH

4 6SHFLI\LQJLVRODWLRQOHYHO
7KHLVRODWLRQOHYHOSDUDPHWHUVSHFLILHVWKHYLHZRIWKHGDWDEDVHSHUPLWWHGDWUDQVDFWLRQDVLW
UHODWHVWRDFWLRQVSHUIRUPHGE\RWKHUVLPXOWDQHRXVO\RFFXUULQJWUDQVDFWLRQV

ISC_TPB_CONCURRENCY
%\GHIDXOWDIWHUDWUDQVDFWLRQVWDUWVLWFDQQRWDFFHVVFRPPLWWHGFKDQJHVWRDWDEOHPDGHE\
RWKHUVLPXOWDQHRXVWUDQVDFWLRQVHYHQWKRXJKLWVKDUHVDFFHVVWRWKHWDEOHZLWKWKHP6XFKD
WUDQVDFWLRQKDVDQLVRODWLRQOHYHORILVFBWSEBFRQFXUUHQF\PHDQLQJLWFDQKDYHFRQFXUUHQWDFFHVV
WRWDEOHVDOVRDFFHVVHGVLPXOWDQHRXVO\E\RWKHUWUDQVDFWLRQV7KHIROORZLQJGHFODUDWLRQ
FUHDWHVD73%VSHFLI\LQJDQLVRODWLRQOHYHORILVFBWSEBFRQFXUUHQF\
static char isc_tpb[] = {isc_tpb_version3,
isc_tpb_write,
isc_tpb_concurrency};

ISC_TPB_READ_COMMITTED
$VHFRQGLVRODWLRQOHYHOLVFBWSEBUHDGBFRPPLWWHGRIIHUVDOOWKHDGYDQWDJHVRIWKH
LVFBWSEBFRQFXUUHQF\LVRODWLRQOHYHODQGDGGLWLRQDOO\HQDEOHVDWUDQVDFWLRQWRDFFHVVFKDQJHV
FRPPLWWHGE\RWKHUVLPXOWDQHRXVWUDQVDFWLRQV7ZRRWKHUSDUDPHWHUVLVFBWSEBUHFBYHUVLRQDQG
LVFBWSEBQRBUHFBYHUVLRQVKRXOGEHXVHGZLWKWKHLVFBWSEBUHDGBFRPPLWWHGSDUDPHWHU7KH\RIIHU
UHILQHGFRQWURORYHUWKHFRPPLWWHGFKDQJHVDWUDQVDFWLRQLVSHUPLWWHGWRDFFHVV
à LVFBWSEBQRBUHFBYHUVLRQWKHGHIDXOWUHILQHPHQWVSHFLILHVWKDWDWUDQVDFWLRQFDQRQO\UHDGWKH
ODWHVWYHUVLRQRIDURZ,IDFKDQJHWRDURZLVSHQGLQJEXWQRW\HWFRPPLWWHGWKHURZ
FDQQRWEHUHDG
à LVFBWSEBUHFBYHUVLRQVSHFLILHVWKDWDWUDQVDFWLRQFDQUHDGWKHODWHVWFRPPLWWHGYHUVLRQRIDURZ
HYHQLIDPRUHUHFHQWXQFRPPLWWHGYHUVLRQLVSHQGLQJ

API GUIDE 49
 CHAPTER 5 WORKING WITH TRANSACTIONS

7KHIROORZLQJGHFODUDWLRQFUHDWHVD73%ZLWKDUHDGFRPPLWWHGLVRODWLRQOHYHODQGVSHFLILHV
WKDWWKHWUDQVDFWLRQFDQUHDGWKHODWHVWFRPPLWWHGYHUVLRQRIDURZ
static char isc_tpb[] = {isc_tpb_version3,
isc_tpb_write,
isc_tpb_read_committed,
isc_tpb_rec_version};

ISC_TPB_CONSISTENCY
,QWHU%DVHDOVRVXSSRUWVDUHVWULFWLYHLVRODWLRQOHYHOLVFBWSEBFRQVLVWHQF\SUHYHQWVDWUDQVDFWLRQ
IURPDFFHVVLQJWDEOHVLIWKH\DUHZULWWHQWRE\RWKHUWUDQVDFWLRQVLWDOVRSUHYHQWVRWKHU
WUDQVDFWLRQVIURPZULWLQJWRDWDEOHRQFHWKLVWUDQVDFWLRQZULWHVWRLW7KLVLVRODWLRQOHYHOLV
GHVLJQHGWRJXDUDQWHHWKDWLIDWUDQVDFWLRQZULWHVWRDWDEOHEHIRUHRWKHUVLPXOWDQHRXVUHDG
DQGZULWHWUDQVDFWLRQVWKHQRQO\LWFDQFKDQJHDWDEOH·VGDWD%HFDXVHLWHVVHQWLDOO\UHVWULFWV
DQGRIWHQSUHYHQWV VKDUHGDFFHVVWRWDEOHVLVFBWSEBFRQVLVWHQF\VKRXOGEHXVHGZLWKFDUH
$73%VKRXOGRQO\VSHFLI\RQHLVRODWLRQPRGHSDUDPHWHU DQGRQHUHILQHPHQWSDUDPHWHULI
LVRODWLRQPRGHLVLVFBWSEBUHDGBFRPPLWWHG ,IPRUHWKDQRQHLVVSHFLILHGODWHUGHFODUDWLRQV
RYHUULGHHDUOLHURQHV
,ID73%LVGHFODUHGWKDWRPLWVWKHLVRODWLRQPRGHSDUDPHWHU,QWHU%DVHLQWHUSUHWVLWDV
LVFBWSEBFRQFXUUHQF\

ISOLATION LEVEL INTERACTIONS

7RGHWHUPLQHWKHSRVVLELOLW\IRUORFNFRQIOLFWVEHWZHHQWZRWUDQVDFWLRQVDFFHVVLQJWKHVDPH
GDWDEDVHHDFKWUDQVDFWLRQ·VLVRODWLRQOHYHODQGDFFHVVPRGHPXVWEHFRQVLGHUHG7KH
IROORZLQJWDEOHVXPPDUL]HVSRVVLEOHFRPELQDWLRQV

isc_tpb_concurrency,
isc_tpb_read_committed isc_tpb_consistency
isc_tpb_rea
isc_tpb_write isc_tpb_read isc_tpb_write d
concurrency, isc_tpb_write Some simultaneous — Conflicts. Conflicts.
read_committed updates may conflict.
isc_tpb_read — — — —
consistency isc_tpb_write Conflicts. — Conflicts. Conflicts.
isc_tpb_read Conflicts. — Conflicts. —
TABLE 5.4 Isolation level interaction with read and write operations

50 INTERBASE 5
STARTING TRANSACTIONS

$VWKLVWDEOHLOOXVWUDWHVLVFBWSEBFRQFXUUHQF\DQGLVFBWSEBUHDGBFRPPLWWHGWUDQVDFWLRQVRIIHUWKH
OHDVWFKDQFHIRUFRQIOLFWV)RUH[DPSOHLIWLVDQLVFBWSEBFRQFXUUHQF\WUDQVDFWLRQZLWK
LVFBWSEBZULWHDFFHVVDQGWLVDQLVFBWSEBUHDGBFRPPLWWHGWUDQVDFWLRQZLWKLVFBWSEBZULWHDFFHVVW
DQGWRQO\FRQIOLFWZKHQWKH\DWWHPSWWRXSGDWHWKHVDPHURZV,IWDQGWKDYHLVFBWSEBUHDG
DFFHVVWKH\QHYHUFRQIOLFWZLWKRWKHUWUDQVDFWLRQV
$QLVFBWSEBFRQVLVWHQF\WUDQVDFWLRQZLWKLVFBWSEBZULWHDFFHVVLVJXDUDQWHHGWKDWLILWJDLQVDFFHVV
WRDWDEOHWKDWLWDORQHFDQXSGDWHDWDEOHEXWLWFRQIOLFWVZLWKDOORWKHUVLPXOWDQHRXV
WUDQVDFWLRQVH[FHSWIRULVFBWSEBFRQFXUUHQF\DQGLVFBWSEBUHDGBFRPPLWWHGWUDQVDFWLRQVUXQQLQJLQ
LVFBWSEBUHDGPRGH$QLVFBWSEBFRQVLVWHQF\WUDQVDFWLRQZLWKLVFBWSEBUHDGDFFHVVLVFRPSDWLEOHZLWK
DQ\RWKHUUHDGRQO\WUDQVDFWLRQEXWFRQIOLFWVZLWKDQ\WUDQVDFWLRQWKDWDWWHPSWVWRLQVHUW
XSGDWHRUGHOHWHGDWD

4 6SHFLI\LQJORFNUHVROXWLRQ
7KHORFNUHVROXWLRQSDUDPHWHUGHVFULEHVZKDWKDSSHQVLIDWUDQVDFWLRQHQFRXQWHUVDQDFFHVV
FRQIOLFWGXULQJDZULWHRSHUDWLRQ XSGDWHDQGGHOHWHRSHUDWLRQVRQH[LVWLQJURZV 7KHUHDUH
WZRSRVVLEOHFKRLFHVIRUWKLVSDUDPHWHU
g LVFBWSEBZDLWWKHGHIDXOWVSHFLILHVWKDWWKHWUDQVDFWLRQVKRXOGZDLWXQWLOORFNHGUHVRXUFHVDUH
UHOHDVHG2QFHWKHUHVRXUFHVDUHUHOHDVHGWKHWUDQVDFWLRQUHWULHVLWVRSHUDWLRQ
g LVFBWSEBQRZDLWVSHFLILHVWKDWWKHWUDQVDFWLRQVKRXOGUHWXUQDORFNFRQIOLFWHUURUZLWKRXWZDLWLQJ
IRUORFNVWREHUHOHDVHG
)RUH[DPSOHWKHIROORZLQJGHFODUDWLRQFUHDWHVD73%ZLWKZULWHDFFHVVDFRQFXUUHQF\
LVRODWLRQPRGHDQGDORFNUHVROXWLRQRILVFBWSEBQRZDLW
static char isc_tpb[] = {isc_tpb_version3,
isc_tpb_write,
isc_tpb_concurrency,
isc_tpb_nowait};

$73%VKRXOGRQO\VSHFLI\RQHORFNUHVROXWLRQSDUDPHWHU,IPRUHWKDQRQHLVVSHFLILHGODWHU
GHFODUDWLRQVRYHUULGHHDUOLHURQHV
,ID73%LVGHFODUHGWKDWRPLWVWKHORFNUHVROXWLRQSDUDPHWHU,QWHU%DVHLQWHUSUHWVLWDV
LVFBWSEBFRQFXUUHQF\

API GUIDE 51
 CHAPTER 5 WORKING WITH TRANSACTIONS

4 6SHFLI\LQJWDEOHUHVHUYDWLRQ
2UGLQDULO\WUDQVDFWLRQVJDLQVSHFLILFDFFHVVWRWDEOHVRQO\ZKHQWKH\DFWXDOO\UHDGIURPRU
ZULWHWRWKHP2SWLRQDOWDEOHUHVHUYDWLRQSDUDPHWHUVFDQEHSDVVHGLQWKH73%7DEOH
UHVHUYDWLRQRSWLRQDOO\GHVFULEHVDQDFFHVVPHWKRGDQGORFNUHVROXWLRQIRUDVSHFLILHGWDEOH
WKDWWKHWUDQVDFWLRQDFFHVVHV:KHQWDEOHUHVHUYDWLRQLVXVHGWDEOHVDUHUHVHUYHGIRUWKH
VSHFLILHGDFFHVVZKHQWKHWUDQVDFWLRQLVVWDUWHGUDWKHUWKDQZKHQWKHWUDQVDFWLRQDFWXDOO\
DFFHVVHVWKHWDEOH7DEOHUHVHUYDWLRQLVRQO\XVHIXOLQDQHQYLURQPHQWZKHUHVLPXOWDQHRXV
WUDQVDFWLRQVVKDUHGDWDEDVHDFFHVV,WKDVWKUHHPDLQSXUSRVHV
g 3UHYHQWSRVVLEOHGHDGORFNVDQGXSGDWHFRQIOLFWVWKDWFDQRFFXULIORFNVDUHWDNHQRQO\ZKHQ
DFWXDOO\QHHGHG WKHGHIDXOWEHKDYLRU 
g 3URYLGHIRUGHSHQGHQF\ORFNLQJWKHORFNLQJRIWDEOHVWKDWPD\EHDIIHFWHGE\WULJJHUVDQG
LQWHJULW\FRQVWUDLQWV:KLOHH[SOLFLWGHSHQGHQF\ORFNLQJLVQRWUHTXLUHGLWFDQDVVXUHWKDW
XSGDWHFRQIOLFWVGRQRWRFFXUEHFDXVHRILQGLUHFWWDEOHFRQIOLFWV
g &KDQJHWKHOHYHORIVKDUHGDFFHVVIRURQHRUPRUHLQGLYLGXDOWDEOHVLQDWUDQVDFWLRQ)RU
H[DPSOHDQLVFBWSEBZULWHWUDQVDFWLRQZLWKDQLVRODWLRQOHYHORILVFBWSEBFRQFXUUHQF\PD\QHHG
H[FOXVLYHXSGDWHULJKWVIRUDVLQJOHWDEOHDQGFRXOGXVHDUHVHUYDWLRQSDUDPHWHUWRJXDUDQWHH
LWVHOIVROHZULWHDFFHVVWRWKHWDEOH
9DOLGUHVHUYDWLRQVDUH
à LVFBWSEBVKDUHGLVFBWSEBORFNBZULWHZKLFKSHUPLWVDQ\WUDQVDFWLRQZLWKDQDFFHVVPRGHRI
LVFBWSEBZULWHDQGLVRODWLRQOHYHOVRILVFBWSEBFRQFXUUHQF\RULVFBWSEBUHDGBFRPPLWWHGWRXSGDWH
ZKLOHRWKHUWUDQVDFWLRQVZLWKWKHVHLVRODWLRQOHYHOVDQGDQDFFHVVPRGHRILVFBWSEBUHDGFDQ
UHDGGDWD
à LVFBWSEBVKDUHGLVFBWSEBORFNBUHDGZKLFKSHUPLWVDQ\WUDQVDFWLRQWRUHDGGDWDDQGDQ\
WUDQVDFWLRQZLWKDQDFFHVVPRGHRILVFBWSEBZULWHWRXSGDWH7KLVLVWKHPRVWOLEHUDO
UHVHUYDWLRQPRGH
à LVFBWSEBSURWHFWHGLVFBWSEBORFNBZULWHZKLFKSUHYHQWVRWKHUWUDQVDFWLRQVIURPXSGDWLQJ2WKHU
WUDQVDFWLRQVZLWKLVRODWLRQOHYHOVRILVFBWSEBFRQFXUUHQF\RULVFBWSEBUHDGBFRPPLWWHGFDQUHDG
GDWDEXWRQO\WKLVWUDQVDFWLRQFDQXSGDWH
à LVFBWSEBSURWHFWHGLVFBWSEBORFNBUHDGZKLFKSUHYHQWVDOOWUDQVDFWLRQVIURPXSGDWLQJEXW
SHUPLWVDOOWUDQVDFWLRQVWRUHDGGDWD
7KHQDPHRIWKHWDEOHWRUHVHUYHPXVWLPPHGLDWHO\IROORZWKHUHVHUYDWLRQSDUDPHWHUV)RU
H[DPSOHWKHIROORZLQJ73%GHFODUDWLRQUHVHUYHVDWDEOH(03/2<((IRUSURWHFWHGUHDG
DFFHVV
static char isc_tpb[] = {isc_tpb_version3,
isc_tpb_write,
isc_tpb_concurrency,

52 INTERBASE 5
STARTING TRANSACTIONS

isc_tpb_nowait,
isc_tpb_protected, isc_tpb_lock_read, "EMPLOYEE"};

6HYHUDOWDEOHVFDQEHUHVHUYHGDWWKHVDPHWLPH7KHIROORZLQJGHFODUDWLRQLOOXVWUDWHVKRZWZR
WDEOHVDUHUHVHUYHGRQHIRUSURWHFWHGUHDGWKHRWKHUIRUSURWHFWHGZULWH
static char isc_tpb[] = {isc_tpb_version3,
isc_tpb_write,
isc_tpb_concurrency,
isc_tpb_nowait,
isc_tpb_protected, isc_tpb_lock_read, "COUNTRY",
isc_tpb_protected, isc_tpb_lock_write, "EMPLOYEE"};

4 8VLQJWKHGHIDXOW73%
3URYLGLQJD73%IRUDWUDQVDFWLRQLVRSWLRQDO,IRQHLVQRWSURYLGHGWKHQD18//SRLQWHU
PXVWEHSDVVHGWRisc_start_transaction()LQSODFHRIDSRLQWHUWRWKH73%,QWKLVFDVH
,QWHU%DVHWUHDWVDWUDQVDFWLRQDVLIWKHIROORZLQJ73%KDGEHHQGHFODUHGIRULW
static char isc_tpb[] = {isc_tpb_version3,
isc_tpb_write,
isc_tpb_concurrency,
isc_tpb_wait};

Calling isc_start_transaction( )
2QFHWUDQVDFWLRQKDQGOHVDQG73%VDUHSUHSDUHGDWUDQVDFWLRQFDQEHVWDUWHGE\FDOOLQJ
isc_start_transaction()XVLQJWKHIROORZLQJV\QWD[
ISC_STATUS isc_start_transaction(
ISC_STATUS *status vector,
isc_tr_handle *trans_handle,
short db_count,
isc_db_handle *&db_handle,
unsigned short tpb_length,
char *tpb_ad);

)RUDWUDQVDFWLRQWKDWUXQVDJDLQVWDVLQJOHGDWDEDVHVHWGEBFRXQWWRGEBKDQGOHVKRXOGEHD
GDWDEDVHKDQGOHVHWZLWKDSUHYLRXVFDOOWRisc_attach_database()WSEBOHQJWKLVWKHVL]HRI
WKH73%SDVVHGLQWKHQH[WSDUDPHWHUDQGWSEBDGLVWKHDGGUHVVRIWKH73%7KHIROORZLQJ
FRGHLOOXVWUDWHVDW\SLFDOFDOOWRisc_start_transaction()
#include <ibase.h>
. . .
ISC_STATUS status_vector[20];

API GUIDE 53
 CHAPTER 5 WORKING WITH TRANSACTIONS

isc_db_handle db1;
isc_tr_handle tr1;
static char isc_tbp[] = {isc_tpb_version3,
isc_tpb_write,
isc_tpb_concurrency,
isc_tpb_wait};
. . .
/* Initialize database and transaction handles here. */
db1 = 0L;
tr1 = 0L;
. . .
/* Code for attaching to database here is omitted. */
isc_start_transaction(status_vector,
&tr1,
1,
&db1,
(unsigned short) sizeof(isc_tpb),
isc_tpb);

$WUDQVDFWLRQFDQEHRSHQHGDJDLQVWPXOWLSOHGDWDEDVHV7RGRVRVHWWKHGEBFRXQWSDUDPHWHU
WRWKHQXPEHURIGDWDEDVHVDJDLQVWZKLFKWKHWUDQVDFWLRQUXQVWKHQIRUHDFKGDWDEDVHUHSHDW
WKHGEBKDQGOHWSEBOHQJWKDQGWSEBDGSDUDPHWHUVDVDJURXSRQFHIRUHDFKGDWDEDVH)RU
H[DPSOHWKHIROORZLQJFRGHIUDJPHQWDVVXPHVWKDWWZRGDWDEDVHVDUHFRQQHFWHGZKHQWKH
WUDQVDFWLRQLVVWDUWHG
isc_start_transaction(status_vector,
&tr1,
2,
&db1,
(unsigned short) sizeof(isc_tpb),
&tpb);
&db2,
(unsigned short) sizeof(isc_tpb),
&tpb);

)RUWKHFRPSOHWHV\QWD[RIisc_start_transaction()VHHSDJH

Calling isc_start_multiple( )
$QDOWHUQDWHPHWKRGIRUVWDUWLQJDWUDQVDFWLRQDJDLQVWPXOWLSOHGDWDEDVHVLVWRXVH
isc_start_multiple()8VLQJisc_start_multiple()LVQRWUHFRPPHQGHGXQOHVV\RX
g $UHXVLQJDODQJXDJHWKDWGRHVQRWVXSSRUWDYDULDEOHQXPEHURIDUJXPHQWVLQDIXQFWLRQFDOO

54 INTERBASE 5
STARTING TRANSACTIONS

g 'RQRWNQRZKRZPDQ\GDWDEDVHV\RXZDQWWRDWWDFKWRZKHQFRGLQJWKHVWDUWRID
WUDQVDFWLRQ
&SURJUDPPHUVVKRXOGVHOGRPQHHGWRXVHWKLVIXQFWLRQ
isc_start_multiple()SDVVHVLQIRUPDWLRQDERXWHDFKWDUJHWGDWDEDVHWR,QWHU%DVHWKURXJKDQ
DUUD\RIWUDQVDFWLRQH[LVWHQFHEORFNV 7(%V 7KHUHPXVWEHRQH7(%IRUHDFKGDWDEDVH
DJDLQVWZKLFKDWUDQVDFWLRQUXQV$7(%LVDVWUXFWXUH\RXPXVWGHFODUHLQ\RXUDSSOLFDWLRQV
DVIROORZV
typdef struct {
long *db_ptr;
long tpb_len;
char *tpb_ptr;
} ISC_TEB;

GEBSWULVDSRLQWHUWRDSUHYLRXVO\GHFODUHGLQLWLDOL]HGDQGSRSXODWHGGDWDEDVHKDQGOHWSEBOHQ
LVWKHVL]HLQE\WHVRIWKHWUDQVDFWLRQSDUDPHWHUEXIIHU 73% WRXVHIRUWKHGDWDEDVHDQG
WSEBSWULVDSRLQWHUWRWKH73%LWVHOI)RULQIRUPDWLRQDERXWGHFODULQJLQLWLDOL]LQJDQG
SRSXODWLQJDGDWDEDVHKDQGOHVHH´&UHDWLQJGDWDEDVHKDQGOHVµRQSDJH )RUPRUH
LQIRUPDWLRQDERXWFUHDWLQJDQGSRSXODWLQJD73%VHH´&UHDWLQJDWUDQVDFWLRQSDUDPHWHU
EXIIHUµRQSDJH 
7RXVHD7(%VWUXFWXUHLQDQDSSOLFDWLRQGHFODUHDQDUUD\YDULDEOHRIW\SH,6&B7(%7KH
QXPEHURIDUUD\GLPHQVLRQVVKRXOGFRUUHVSRQGWRWKHQXPEHURIGDWDEDVHVWKDWWKH
WUDQVDFWLRQUXQVDJDLQVW)RUH[DPSOHWKHIROORZLQJGHFODUDWLRQFUHDWHVDQDUUD\RIWZR7(%V
FDSDEOHRIVXSSRUWLQJWZRGDWDEDVHV
ISC_TEB teb_array[2];

2QFHDQDUUD\RI7(%VLVGHFODUHGDQGFRUUHVSRQGLQJ7%3VDUHFUHDWHGDQGSRSXODWHGIRU
HDFKGDWDEDVHYDOXHVPD\EHDVVLJQHGWRWKHDSSURSULDWHILHOGVLQWKH7(%V)RUH[DPSOHWKH
IROORZLQJFRGHLOOXVWUDWHVKRZWZR7(%VDUHILOOHG
. . .
ISC_STATUS status_vector[20];
isc_db_handle db1, db2;
isc_tr_handle trans;
ISC_TEB teb_array[2];
. . .
db1 = db2 = 0L;
trans = 0L;
/* Code assumes that two TPBs, isc_tpb1, and isc_tpb2, are created here. */
/* Code assumes databases are attached here. */
/* assign values to TEB array */
teb_array[0].db_ptr = &db1;
teb_array[0].tpb_len = sizeof(isc_tpb1);

API GUIDE 55
 CHAPTER 5 WORKING WITH TRANSACTIONS

teb_array[0].tpb_ptr = isc_tpb1;
teb_array[1].db_ptr = &db2;
teb_array[1].tpb_len = sizeof(isc_tpb2);
teb_array[1].tpb_ptr = isc_tpb2;
. . .

$IWHUWKH7(%VDUHORDGHGZLWKYDOXHVisc_start_multiple()FDQEHFDOOHGXVLQJWKH
IROORZLQJV\QWD[
ISC_STATUS isc_start_multiple(
ISC_STATUS *status_vector,
isc_tr_handle *trans_handle,
short db_handle_count,
void *teb_vector_address);

)RUH[DPSOHWKHIROORZLQJVWDWHPHQWVVWDUWVDWZRGDWDEDVHWUDQVDFWLRQ
. . .
ISC_STATUS status_vector[20];
isc_db_handle db1, db2;
isc_tr_handle trans;
ISC_TEB teb_array[2];
. . .
db1 = db2 = 0L;
trans = 0L;
/* Code assumes that two TPBs, isc_tpb1, and isc_tpb2, are created here. */
/* Code assumes databases are attached here. */
/* assign values to TEB array */
teb_array[0].db_ptr = &db1;
teb_array[0].tpb_len = sizeof(isc_tpb1);
teb_array[0].tpb_ptr = isc_tpb1;
teb_array[1].db_ptr = &db2;
teb_array[1].tpb_len = sizeof(isc_tpb2);
teb_array[1].tpb_ptr = isc_tpb2;
/* Start the transaction */
isc_start_multiple(status_vector, &trans, 2, teb_array);
. . .

Ending transactions
:KHQDWUDQVDFWLRQ·VWDVNVDUHFRPSOHWHRUDQHUURUSUHYHQWVDWUDQVDFWLRQIURPFRPSOHWLQJ
WKHWUDQVDFWLRQPXVWEHHQGHGWRVHWWKHGDWDEDVHWRDFRQVLVWHQWVWDWH7KHUHDUHWZR$3,
IXQFWLRQVWKDWHQGWUDQVDFWLRQV

56 INTERBASE 5
ENDING TRANSACTIONS

g isc_commit_transaction()PDNHVDWUDQVDFWLRQ·VFKDQJHVSHUPDQHQWLQWKHGDWDEDVH)RU
WUDQVDFWLRQVWKDWVSDQGDWDEDVHVWKLVIXQFWLRQSHUIRUPVDQDXWRPDWLFWZRSKDVHFRPPLWWR
HQVXUHWKDWDOOFKDQJHVDUHPDGHVXFFHVVIXOO\
g isc_rollback_transaction()XQGRHVDWUDQVDFWLRQ·VFKDQJHVUHWXUQLQJWKHGDWDEDVHWRLWV
SUHYLRXVVWDWHEHIRUHWKHWUDQVDFWLRQVWDUWHG7KLVIXQFWLRQLVW\SLFDOO\XVHGZKHQRQHRU
PRUHHUURUVRFFXUWKDWSUHYHQWDWUDQVDFWLRQIURPFRPSOHWLQJVXFFHVVIXOO\
%RWKisc_commit_transaction()DQGisc_rollback_transaction()FORVHWKHUHFRUGVWUHDPV
DVVRFLDWHGZLWKWKHWUDQVDFWLRQUHLQLWLDOL]HWKHWUDQVDFWLRQQDPHWR]HURDQGUHOHDVHV\VWHP
UHVRXUFHVDOORFDWHGIRUWKHWUDQVDFWLRQ)UHHGV\VWHPUHVRXUFHVDUHDYDLODEOHIRUVXEVHTXHQW
XVHE\DQ\DSSOLFDWLRQRUSURJUDP
isc_rollback_transaction()LVIUHTXHQWO\XVHGLQVLGHHUURUKDQGOLQJURXWLQHVWRFOHDQXS
WUDQVDFWLRQVZKHQHUURUVRFFXU,WFDQDOVREHXVHGWRUROOEDFNDSDUWLDOO\FRPSOHWHG
WUDQVDFWLRQSULRUWRUHWU\LQJLWDQGLWFDQEHXVHGWRUHVWRUHDGDWDEDVHWRLWVSULRUVWDWHLID
SURJUDPHQFRXQWHUVDQXQUHFRYHUDEOHHUURU
7KH$3,RIIHUVWKUHHDGGLWLRQDOIXQFWLRQVIRUFRQWUROOLQJWUDQVDFWLRQV
g isc_commit_retaining()FRPPLWVDWUDQVDFWLRQEXWUHWDLQVWKHFXUUHQWWUDQVDFWLRQ·V
FRQWH[W³WKHV\VWHPUHVRXUFHVDQGFXUVRUVWDWHVXVHGLQWKHWUDQVDFWLRQ³ZLWKRXWUHTXLULQJ
WKHRYHUKHDGRIHQGLQJDWUDQVDFWLRQVWDUWLQJDQHZRQHDQGUHHVWDEOLVKLQJFXUVRUVWDWHV,Q
DEXV\PXOWLXVHUHQYLURQPHQWPDLQWDLQLQJWUDQVDFWLRQFRQWH[WIRUHDFKXVHUVSHHGVXS
SURFHVVLQJDQGXVHVIHZHUV\VWHPUHVRXUFHVWKDQFORVLQJDWUDQVDFWLRQDQGRSHQLQJDQHZ
RQH
g isc_prepare_transaction()DQGisc_prepare_transaction2() HQDEOHDQDSSOLFDWLRQWR
SHUIRUPWKHILUVWSKDVHRIDQDXWRPDWLFWZRSKDVHFRPPLWLQLWVRZQWLPHWKHQLVVXHDFDOO
WRisc_commit_transaction()WRFRPSOHWHWKHFRPPLW

,03257$17 ,IWKHSURJUDPHQGVEHIRUHDWUDQVDFWLRQHQGVDWUDQVDFWLRQLVDXWRPDWLFDOO\UROOHGEDFNEXW
GDWDEDVHVDUHQRWFORVHG,IDSURJUDPHQGVZLWKRXWFORVLQJWKHGDWDEDVHGDWDORVVRU
FRUUXSWLRQLVSRVVLEOH7KHUHIRUHRSHQGDWDEDVHVVKRXOGDOZD\VEHFORVHGE\LVVXLQJDQ
H[SOLFLWFDOOWRisc_detach_database()
)RUPRUHLQIRUPDWLRQDERXWGHWDFKLQJIURPDGDWDEDVHVHH&KDSWHU´:RUNLQJZLWK
'DWDEDVHVµ

API GUIDE 57
 CHAPTER 5 WORKING WITH TRANSACTIONS

Using isc_commit_transaction( )
8VHisc_commit_transaction()WRZULWHWUDQVDFWLRQFKDQJHVSHUPDQHQWO\WRDGDWDEDVH
isc_commit_transaction()FORVHVWKHUHFRUGVWUHDPVDVVRFLDWHGZLWKWKHWUDQVDFWLRQUHVHWV
WKHWUDQVDFWLRQQDPHWR]HURDQGIUHHVV\VWHPUHVRXUFHVDVVLJQHGWRWKHWUDQVDFWLRQIRURWKHU
XVHV7KHFRPSOHWHV\QWD[IRU isc_commit_transaction()LV
ISC_STATUS isc_commit_transaction(
ISC_STATUS *status_vector,
isc_tr_handle *trans_handle);

)RUH[DPSOHWKHIROORZLQJFDOOFRPPLWVDWUDQVDFWLRQ
isc_commit_transaction(status_vector, &trans);

ZKHUHVWDWXVBYHFWRULVDSRLQWHUWRDSUHYLRXVO\GHFODUHGHUURUVWDWXVYHFWRUDQGWUDQVLVD
SRLQWHUWRDSUHYLRXVO\GHFODUHGDQGLQLWLDOL]HGWUDQVDFWLRQKDQGOH

7,3 (YHQWUDQVDFWLRQVVWDUWHGZLWKDQDFFHVVPRGHRILVFBWSEBUHDGVKRXOGEHHQGHGZLWKDFDOOWR
isc_commit_transaction()UDWKHUWKDQisc_rollback_transaction()7KHGDWDEDVHLVQRW
FKDQJHGEXWWKHRYHUKHDGUHTXLUHGWRVWDUWVXEVHTXHQWWUDQVDFWLRQVLVJUHDWO\UHGXFHG

4 8VLQJLVFBFRPPLWBUHWDLQLQJ 
7RZULWHWUDQVDFWLRQFKDQJHVWRWKHGDWDEDVHZLWKRXWHVWDEOLVKLQJDQHZWUDQVDFWLRQFRQWH[W³
WKHQDPHVV\VWHPUHVRXUFHVDQGFXUUHQWVWDWHRIFXUVRUVXVHGLQDWUDQVDFWLRQ³XVH
isc_commit_retaining()LQVWHDGRIisc_commit_transaction(),QDEXV\PXOWLXVHU
HQYLURQPHQWPDLQWDLQLQJWKHWUDQVDFWLRQFRQWH[WIRUHDFKXVHUVSHHGVXSSURFHVVLQJDQG
XVHVIHZHUV\VWHPUHVRXUFHVWKDQFORVLQJDQGVWDUWLQJDQHZWUDQVDFWLRQIRUHDFKDFWLRQ7KH
FRPSOHWHV\QWD[IRUisc_commit_retaining()LV
ISC_STATUS isc_commit_retaining(
ISC_STATUS *status_vector,
isc_tr_handle *trans_handle);

isc_commit_retaining()ZULWHVDOOSHQGLQJFKDQJHVWRWKHGDWDEDVHHQGVWKHFXUUHQW
WUDQVDFWLRQZLWKRXWFORVLQJLWVUHFRUGVWUHDPDQGFXUVRUVDQGZLWKRXWIUHHLQJLWVV\VWHP
UHVRXUFHVWKHQVWDUWVDQHZWUDQVDFWLRQDQGDVVLJQVWKHH[LVWLQJUHFRUGVWUHDPVDQGV\VWHP
UHVRXUFHVWRWKHQHZWUDQVDFWLRQ
)RUH[DPSOHWKHIROORZLQJFDOOFRPPLWVDVSHFLILHGWUDQVDFWLRQSUHVHUYLQJWKHFXUUHQWFXUVRU
VWDWXVDQGV\VWHPUHVRXUFHV
isc_commit_retaining(status_vector, &trans);

ZKHUHVWDWXVBYHFWRULVDSRLQWHUWRDSUHYLRXVO\GHFODUHGHUURUVWDWXVYHFWRUDQGWUDQVLVD
SRLQWHUWRDSUHYLRXVO\GHFODUHGDQGLQLWLDOL]HGWUDQVDFWLRQKDQGOH

58 INTERBASE 5
ENDING TRANSACTIONS

$FDOOWRisc_rollback_transaction()LVVXHGDIWHUisc_commit_retaining()RQO\UROOVEDFN
XSGDWHVDQGZULWHVRFFXUULQJDIWHUWKHFDOOWRisc_commit_retaining()

4 8VLQJLVFBSUHSDUHBWUDQVDFWLRQ
:KHQDWUDQVDFWLRQLVFRPPLWWHGDJDLQVWPXOWLSOHGDWDEDVHVXVLQJ
isc_commit_transaction(),QWHU%DVHDXWRPDWLFDOO\SHUIRUPVDWZRSKDVHFRPPLW'XULQJ
WKHILUVWSKDVHRIWKHFRPPLWWKH,QWHU%DVHHQJLQHSROOVDOOGDWDEDVHSDUWLFLSDQWVWRPDNH
VXUHWKH\DUHVWLOODYDLODEOHZULWHVDPHVVDJHGHVFULELQJWKHWUDQVDFWLRQWRWKH
5'%75$16$&7,21B'(6&5,37,21ILHOGRIWKH5'%75$16$&7,21V\VWHPWDEOHWKHQ
SXWVWKHWUDQVDFWLRQLQWRDOLPERVWDWH,WLVGXULQJWKHVHFRQGSKDVHWKDWWUDQVDFWLRQFKDQJHV
DUHDFWXDOO\FRPPLWWHGWRWKHGDWDEDVH
6RPHDSSOLFDWLRQVPD\KDYHWKHLURZQDGGLWLRQDOUHTXLUHPHQWVWRPDNHRIWKHWZRSKDVH
FRPPLW7KHVHDSSOLFDWLRQVFDQFDOO isc_prepare_transaction()WRH[HFXWHWKHILUVWSKDVHRI
WKHWZRSKDVHFRPPLWWKHQSHUIRUPWKHLURZQDGGLWLRQDOWDVNVEHIRUHFRPSOHWLQJWKH
FRPPLWZLWKDFDOOWRisc_commit_transaction()
7KHV\QWD[IRUisc_prepare_transaction()LV
ISC_STATUS isc_prepare_transaction(
ISC_STATUS *status_vector,
isc_tr_handle *trans_handle);

)RUH[DPSOHWKHIROORZLQJFRGHIUDJPHQWLOOXVWUDWHVKRZDQDSSOLFDWLRQPLJKWFDOO
isc_prepare_transaction()WKHQLWVRZQURXWLQHVEHIRUHFRPSOHWLQJDFRPPLWZLWK
isc_commit_transaction()
ISC_STATUS status_vector[20];
isc_db_handle db1;
isc_tr_handle trans;
. . .
/* Initialize handles. */
db1 = 0L;
trans = 0L;
. . .
/* Code assumes a database is attached here, */
/* and a transaction started. */
. . .
/* Perform first phase of two-phase commit. */
isc_prepare_transaction(status_vector, &trans);
/* Application does its own processing here. */
my_app_function();
/* Now complete the two-phase commit. */
isc_commit_transaction(status_vector, &trans);

API GUIDE 59
 CHAPTER 5 WORKING WITH TRANSACTIONS

,03257$17 ,WLVJHQHUDOO\DGDQJHURXVSUDFWLFHWRGHOD\WKHVHFRQGSKDVHRIWKHFRPPLWDIWHU
FRPSOHWLQJWKHILUVWEHFDXVHGHOD\VLQFUHDVHWKHFKDQFHWKDWQHWZRUNRUVHUYHUSUREOHPVFDQ
RFFXUEHWZHHQSKDVHV

Using isc_prepare_transaction2( )
/LNHisc_prepare_transaction()isc_prepare_transaction2()SHUIRUPVWKHILUVWSKDVHRI
DWZRSKDVHFRPPLWH[FHSWWKDWisc_prepare_transaction2()HQDEOHV
DQDSSOLFDWLRQWRVXSSO\LWVRZQWUDQVDFWLRQGHVFULSWLRQIRULQVHUWLRQLQWRWKH
5'%75$16$&7,21B'(6&5,37,21ILHOGRIWKH5'%75$16$&7,21
V\VWHPWDEOH

,03257$17 'RQRWXVHWKLVFDOOZLWKRXWILUVWH[DPLQLQJDQGXQGHUVWDQGLQJWKHLQIRUPDWLRQ,QWHU%DVH
VWRUHVLQ5'%75$16$&7,21B'(6&5,37,21GXULQJDQDXWRPDWLFWZRSKDVHFRPPLW
6WRUDJHRILPSURSHURULQFRPSOHWHLQIRUPDWLRQFDQSUHYHQWGDWDEDVHUHFRYHU\LIWKH
WZRSKDVHFRPPLWIDLOV
)RUWKHFRPSOHWHV\QWD[RIisc_prepare_transaction2()VHHSDJH

Using isc_rollback_transaction( )
8VHisc_rollback_transaction()WRUHVWRUHWKHGDWDEDVHWRLWVFRQGLWLRQSULRUWRWKHVWDUWRI
WKHWUDQVDFWLRQisc_rollback_transaction()DOVRFORVHVWKHUHFRUGVWUHDPVDVVRFLDWHGZLWK
WKHWUDQVDFWLRQUHVHWVWKHWUDQVDFWLRQQDPHWR]HURDQGIUHHVV\VWHPUHVRXUFHVDVVLJQHGWR
WKHWUDQVDFWLRQIRURWKHUXVHVisc_rollback_transaction()W\SLFDOO\DSSHDUVLQ
HUURUKDQGOLQJURXWLQHV7KHV\QWD[IRUisc_rollback_transaction()LV
ISC_STATUS isc_rollback_transaction(
ISC_STATUS *status_vector,
isc_tr_handle *trans_handle);

)RUH[DPSOHWKHIROORZLQJFDOOUROOVEDFNDWUDQVDFWLRQ
isc_rollback_transaction(status_vector, &trans);
ZKHUHVWDWXVBYHFWRULVDSRLQWHUWRDSUHYLRXVO\GHFODUHGHUURUVWDWXVYHFWRUDQGWUDQVLVD
SRLQWHUWRDSUHYLRXVO\GHFODUHGDQGLQLWLDOL]HGWUDQVDFWLRQKDQGOH

60 INTERBASE 5
 CHAPTER

Working with Dynamic SQL

Chapter6
6
7KLVFKDSWHUGHVFULEHVKRZWRXVH$3,G\QDPLF64/ '64/ IXQFWLRQVWRKDQGOH
G\QDPLFDOO\FUHDWHG64/VWDWHPHQWVIRUGDWDGHILQLWLRQDQGPDQLSXODWLRQ8VLQJORZOHYHO
$3,FDOOVHQDEOHVFOLHQWDSSOLFDWLRQVWREXLOG64/VWDWHPHQWVRUVROLFLWWKHPIURPHQGXVHUV
DWUXQWLPHSURYLGLQJHQGXVHUVZLWKDIDPLOLDUGDWDEDVHLQWHUIDFH,WDOVRSURYLGHV
DSSOLFDWLRQVGHYHORSHUVORZOHYHODFFHVVWR,QWHU%DVHIHDWXUHVVXFKDVPXOWLSOHGDWDEDVHVQRW
QRUPDOO\DYDLODEOHDWDKLJKHUOHYHOZLWKHPEHGGHG'64/VWDWHPHQWV)RUH[DPSOHWKH
,QWHU%DVHisqlXWLOLW\LVD'64/DSSOLFDWLRQEXLOWRQORZOHYHO$3,FDOOV
$OO$3,'64/IXQFWLRQQDPHVEHJLQZLWKisc_dsqlWRPDNHLWHDVLHUWRGLVWLQJXLVKWKHP
IURPRWKHU$3,FDOOV

Overview of the DSQL programming process

%XLOGLQJDQGH[HFXWLQJ'64/DSSOLFDWLRQVZLWKWKH$3,LQYROYHWKHIROORZLQJJHQHUDOVWHSV
g (PEHGGLQJ'64/$3,IXQFWLRQVLQDQDSSOLFDWLRQ
g 8VLQJKRVWODQJXDJHIDFLOLWLHVVXFKDVGDWDW\SHVDQGPDFURVWRSURYLGHLQSXWDQGRXWSXW
DUHDVIRUSDVVLQJVWDWHPHQWVDQGSDUDPHWHUVDWUXQWLPH
g 3URJUDPPLQJPHWKRGVWKDWXVHWKHVHVWDWHPHQWVDQGIDFLOLWLHVWRSURFHVV64/VWDWHPHQWVDW
UXQWLPH
7KHVHVWHSVDUHGHVFULEHGLQGHWDLOWKURXJKRXWWKLVFKDSWHU

61
 CHAPTER 6 WORKING WITH DYNAMIC SQL

DSQL API limitations

$OWKRXJK'64/RIIHUVPDQ\DGYDQWDJHVLWDOVRKDVWKHIROORZLQJOLPLWDWLRQV
g '\QDPLFWUDQVDFWLRQSURFHVVLQJLVQRWSHUPLWWHGDOOQDPHGWUDQVDFWLRQVPXVWEHGHFODUHGDW
FRPSLOHWLPH
g '\QDPLFDFFHVVWR%OREDQGDUUD\GDWDLVQRWVXSSRUWHG%OREDQGDUUD\GDWDFDQEHDFFHVVHG
EXWRQO\WKURXJKVWDQGDUGVWDWLFDOO\SURFHVVHG64/VWDWHPHQWVRUWKURXJKORZOHYHO$3,
FDOOV
g 'DWDEDVHFUHDWLRQLVUHVWULFWHGWR&5($7('$7$%$6(VWDWHPHQWVH[HFXWHGZLWKLQWKHFRQWH[W
RI(;(&87(,00(',$7(
)RUPRUHLQIRUPDWLRQDERXWGDWDEDVHDFFHVVLQ'64/VHH´$FFHVVLQJGDWDEDVHVµRQ
SDJH )RUPRUHLQIRUPDWLRQDERXWKDQGOLQJWUDQVDFWLRQVLQ'64/DSSOLFDWLRQVVHH
´+DQGOLQJWUDQVDFWLRQVµRQSDJH )RUPRUHLQIRUPDWLRQDERXWZRUNLQJZLWK%OREGDWDLQ
'64/VHH´3URFHVVLQJ%OREGDWDµRQSDJH )RUPRUHLQIRUPDWLRQDERXWKDQGOLQJDUUD\
GDWDLQ'64/VHH´3URFHVVLQJDUUD\GDWDµRQSDJH )RUPRUHLQIRUPDWLRQDERXWG\QDPLF
FUHDWLRQRIGDWDEDVHVVHH´&UHDWLQJDGDWDEDVHµRQSDJH 

Accessing databases
7KH,QWHU%DVH$3,SHUPLWVDSSOLFDWLRQVWRDWWDFKWRPXOWLSOHGDWDEDVHVVLPXOWDQHRXVO\XVLQJ
GDWDEDVHKDQGOHV'DWDEDVHKDQGOHVPXVWEHGHFODUHGDQGLQLWLDOL]HGZKHQDQDSSOLFDWLRQLV
FRPSLOHG6HSDUDWHGDWDEDVHKDQGOHVVKRXOGEHVXSSOLHGDQGLQLWLDOL]HGIRUHDFKGDWDEDVH
DFFHVVHGVLPXOWDQHRXVO\)RUH[DPSOHWKHIROORZLQJFRGHFUHDWHVDVLQJOHKDQGOHGEDQG
LQLWLDOL]HVLWWR]HUR
#include <ibase.h>
isc_db_handle db1;
. . .
db1 = 0L;

2QFHGHFODUHGDQGLQLWLDOL]HGDGDWDEDVHKDQGOHFDQEHDVVLJQHGG\QDPLFDOO\WRDGDWDEDVHDW
UXQWLPHDVIROORZV
#include <ibase.h>
. . .
char dbname[129];
ISC_STATUS status_vector[20];
. . .
prompt_user("Name of database to open: ");

62 INTERBASE 5
DSQL API LIMITATIONS

gets(dbname);
isc_attach_database(status_vector, 0, dbname, &db1, NULL, NULL);

$GDWDEDVHKDQGOHFDQEHXVHGWRDWWDFKWRGLIIHUHQWGDWDEDVHVDVORQJDVDSUHYLRXVO\DWWDFKHG
GDWDEDVHLVILUVWGHWDFKHGZLWKisc_detach_database()ZKLFKDXWRPDWLFDOO\VHWVGDWDEDVH
KDQGOHVWR18//7KHIROORZLQJVWDWHPHQWVGHWDFKIURPDGDWDEDVHVHWWKHGDWDEDVHKDQGOH
WR]HURDQGDWWDFKWRDQHZGDWDEDVH
isc_detach_database(status_vector, &db1);
isc_attach_database(status_vector, 0, "employee.gdb", &db1, NULL, NULL);

)RUPRUHLQIRUPDWLRQDERXW$3,IXQFWLRQFDOOVIRUGDWDEDVHVVHH&KDSWHU´:RUNLQJZLWK
'DWDEDVHVµ

Handling transactions
,QWHU%DVHUHTXLUHVWKDWDOOWUDQVDFWLRQKDQGOHVEHGHFODUHGZKHQDQDSSOLFDWLRQLVFRPSLOHG
2QFHIL[HGDWFRPSLOHWLPHWUDQVDFWLRQKDQGOHVFDQQRWEHFKDQJHGDWUXQWLPHQRUFDQQHZ
KDQGOHVEHGHFODUHGG\QDPLFDOO\DWUXQWLPH0RVW$3,IXQFWLRQVWKDWSURFHVV64/
VWDWHPHQWVDWUXQWLPHVXFKDVisc_dsql_describe()isc_dsql_describe_bind()
isc_dsql_execute()isc_dsql_execute2()isc_dsql_execute_immediate()
isc_dsql_exec_immed2()DQGisc_dsql_prepare()VXSSRUWWKHLQFOXVLRQRIDWUDQVDFWLRQ
KDQGOHSDUDPHWHU7KH64/VWDWHPHQWVSURFHVVHGE\WKHVHIXQFWLRQVFDQQRWSDVVWUDQVDFWLRQ
KDQGOHVHYHQLIWKH64/V\QWD[IRUWKHVWDWHPHQWSHUPLWVWKHXVHRID75$16$&7,21FODXVH
%HIRUHDWUDQVDFWLRQKDQGOHFDQEHXVHGLWPXVWEHGHFODUHGDQGLQLWLDOL]HGWR]HUR7KH
IROORZLQJFRGHGHFODUHVLQLWLDOL]HVDQGXVHVDWUDQVDFWLRQKDQGOHLQDQ$3,FDOOWKDWDOORFDWHV
DQGSUHSDUHVDQ64/VWDWHPHQWIRUH[HFXWLRQ
#include <ibase.h>
. . .
isc_tr_handle trans; /* Declare a transaction handle. */
isc_stmt_handle stmt; /* Declare a statement handle. */
char *sql_stmt = "SELECT * FROM EMPLOYEE";
isc_db_handle db1;
ISC_STATUS status_vector[20];
. . .
trans = 0L; /* Initialize the transaction handle to zero. */
stmt = NULL; /* Set handle to NULL before allocation. */
/* This code assumes both that a database attachment is made, */
/* and a transaction is started here. */
. . .
/* Allocate the SQL statement handle. */
isc_dsql_allocate_statement(status_vector, &db1, &stmt);

API GUIDE 63
 CHAPTER 6 WORKING WITH DYNAMIC SQL

/* Prepare the statement for execution. */

isc_dsql_prepare(status_vector, &trans, &stmt, 0, sql_stmt, 1, NULL);
Note 7KH64/6(775$16$&7,21VWDWHPHQWFDQQRWEHSUHSDUHGZLWK
isc_dsql_prepare()EXWLWFDQEHSURFHVVHGZLWKisc_dsql_execute_immediate()LI
 3UHYLRXVWUDQVDFWLRQVDUHILUVWFRPPLWWHGRUUROOHGEDFN
 7KHWUDQVDFWLRQKDQGOHLVVHWWR18//
)RUPRUHLQIRUPDWLRQDERXWXVLQJ64/VWDWHPHQWVVHHWKH3URJUDPPHU·V*XLGH)RUPRUH
LQIRUPDWLRQDERXW64/VWDWHPHQWV\QWD[VHHWKH/DQJXDJH5HIHUHQFH

Creating a database
7RFUHDWHDQHZGDWDEDVHLQDQ$3,DSSOLFDWLRQ
 'HWDFKIURPDQ\FXUUHQWO\DWWDFKHGGDWDEDVHVZLWKisc_detach_database()
'HWDFKLQJIURPDGDWDEDVHDXWRPDWLFDOO\VHWVLWVGDWDEDVHKDQGOHWR18//
 %XLOGWKH&5($7('$7$%$6(VWDWHPHQWWRSURFHVV
 ([HFXWHWKHVWDWHPHQWZLWKisc_dsql_execute_immediate()RU
isc_dsql_exec_immed2()
)RUH[DPSOHWKHIROORZLQJVWDWHPHQWVGLVFRQQHFWIURPDQ\FXUUHQWO\DWWDFKHGGDWDEDVHVDQG
FUHDWHDQHZGDWDEDVH$Q\H[LVWLQJGDWDEDVHKDQGOHVDUHVHWWR18//VRWKDWWKH\FDQEH
XVHGWRFRQQHFWWRWKHQHZGDWDEDVHLQIXWXUH'64/VWDWHPHQWV
char *str = "CREATE DATABASE \"new_emp.gdb\"";
. . .
isc_detach_database(status_vector, &db1);
isc_dsql_execute_immediate(status_vector, &db1, &trans, 0, str, 1,
NULL);

Processing Blob data

%ORESURFHVVLQJLVQRWGLUHFWO\VXSSRUWHGXVLQJ'64/QRUDUH%OREFXUVRUVVXSSRUWHG
$SSOLFDWLRQVWKDWSURFHVV64/VWDWHPHQWVFDQXVH$3,FDOOVWRKDQGOH%ORESURFHVVLQJ)RU
PRUHLQIRUPDWLRQDERXWSURFHVVLQJ%OREGDWDVHH&KDSWHU´:RUNLQJZLWK%ORE'DWDµ

64 INTERBASE 5
WRITING AN API APPLICATION TO PROCESS SQL STATEMENTS

Processing array data

$UUD\SURFHVVLQJLVQRWGLUHFWO\VXSSRUWHGXVLQJ'64/'64/DSSOLFDWLRQVFDQXVH$3,FDOOV
WRSURFHVVDUUD\GDWD)RUPRUHLQIRUPDWLRQDERXWDUUD\FDOOVVHH&KDSWHU´:RUNLQJZLWK
$UUD\'DWDµ

Writing an API application to process SQL statements

:ULWLQJDQ$3,DSSOLFDWLRQWKDWSURFHVVHV64/VWDWHPHQWVHQDEOHVDGHYHORSHUWRFRGH
GLUHFWO\WR,QWHU%DVHDWDORZOHYHOZKLOHSUHVHQWLQJHQGXVHUVDIDPLOLDU64/LQWHUIDFH$3,
64/DSSOLFDWLRQVDUHHVSHFLDOO\XVHIXOZKHQDQ\RIWKHIROORZLQJDUHQRWNQRZQXQWLO
UXQWLPH
g 7KHWH[WRIWKH64/VWDWHPHQW
g 7KHQXPEHURIKRVWYDULDEOHV
g 7KHGDWDW\SHVRIKRVWYDULDEOHV
g 5HIHUHQFHVWRGDWDEDVHREMHFWV
:ULWLQJDQ$3,'64/DSSOLFDWLRQLVPRUHFRPSOH[WKDQSURJUDPPLQJHPEHGGHG64/
DSSOLFDWLRQVZLWKUHJXODU64/EHFDXVHIRUPRVW'64/RSHUDWLRQVWKHDSSOLFDWLRQQHHGV
H[SOLFLWO\WRDOORFDWHDQGSURFHVVDQH[WHQGHG64/GHVFULSWRUDUHD ;64/'$ GDWDVWUXFWXUH
WRSDVVGDWDWRDQGIURPWKHGDWDEDVH
7RXVHWKH$3,WRSURFHVVD'64/VWDWHPHQWIROORZWKHVHEDVLFVWHSV
 'HWHUPLQHLI$3,FDOOVFDQSURFHVVWKH64/VWDWHPHQW
 5HSUHVHQWWKH64/VWDWHPHQWDVDFKDUDFWHUVWULQJLQWKHDSSOLFDWLRQ
 ,IQHFHVVDU\DOORFDWHRQHRUPRUH;64/'$VIRULQSXWSDUDPHWHUVDQGUHWXUQ
YDOXHV
 8VHDSSURSULDWH$3,SURJUDPPLQJPHWKRGVWRSURFHVVWKH64/VWDWHPHQW

Determining if API calls can process an SQL statement

([FHSWDVQRWHGHDUOLHULQWKLVFKDSWHU'64/IXQFWLRQVFDQSURFHVVPRVW64/VWDWHPHQWV
)RUH[DPSOH'64/FDQSURFHVVGDWDPDQLSXODWLRQVWDWHPHQWVVXFKDV'(/(7(DQG,16(57
GDWDGHILQLWLRQVWDWHPHQWVVXFKDV$/7(57$%/(DQG&5($7(,1'(;DQG6(/(&7
VWDWHPHQWV

API GUIDE 65
 CHAPTER 6 WORKING WITH DYNAMIC SQL

7KHIROORZLQJWDEOHOLVWV64/VWDWHPHQWVWKDWFDQQRWEHSURFHVVHGE\'64/IXQFWLRQV

Statement Statement
CLOSE DECLARE CURSOR

DESCRIBE EXECUTE

EXECUTE IMMEDIATE FETCH

OPEN PREPARE

TABLE 6.1 SQL statements that cannot be processed by the API

7KHVHVWDWHPHQWVDUHXVHGWRSURFHVV'64/UHTXHVWVRUWRKDQGOH64/FXUVRUVZKLFKPXVW
DOZD\VEHVSHFLILHGZKHQDQDSSOLFDWLRQLVZULWWHQ$WWHPSWLQJWRXVHWKHPZLWK'64/
UHVXOWVLQUXQWLPHHUURUV

Representing an SQL statement as a character string

:LWKLQD'64/DSSOLFDWLRQDQ64/VWDWHPHQWFDQFRPHIURPGLIIHUHQWVRXUFHV,WPLJKW
FRPHGLUHFWO\IURPDXVHUZKRHQWHUVDVWDWHPHQWDWDSURPSWDVGRHVisql2ULWPLJKWEH
JHQHUDWHGE\WKHDSSOLFDWLRQLQUHVSRQVHWRXVHULQWHUDFWLRQ:KDWHYHUWKHVRXUFHRIWKH64/
VWDWHPHQWLWPXVWEHUHSUHVHQWHGDVDQ64/VWDWHPHQWVWULQJDFKDUDFWHUVWULQJWKDWLVSDVVHG
WR'64/IRUSURFHVVLQJ
64/VWDWHPHQWVWULQJVGRQRWEHJLQZLWKWKH(;(&64/SUHIL[RUHQGZLWKDVHPLFRORQ  DV
WKH\GRLQW\SLFDOHPEHGGHGDSSOLFDWLRQV)RUH[DPSOHWKHIROORZLQJKRVWODQJXDJHYDULDEOH
GHFODUDWLRQLVDYDOLG64/VWDWHPHQWVWULQJ
char *str = "DELETE FROM CUSTOMER WHERE CUST_NO = 256";

Note 7KHVHPLFRORQWKDWDSSHDUVDWWKHHQGRIWKLVFKDUGHFODUDWLRQLVD&WHUPLQDWRUDQG
QRWSDUWRIWKH64/VWDWHPHQWVWULQJ

Specifying parameters in SQL statement strings

64/VWDWHPHQWVWULQJVRIWHQLQFOXGHYDOXHSDUDPHWHUVH[SUHVVLRQVWKDWHYDOXDWHWRDVLQJOH
QXPHULFRUFKDUDFWHUYDOXH3DUDPHWHUVFDQEHXVHGDQ\ZKHUHLQVWDWHPHQWVWULQJVZKHUH64/
H[SHFWVDYDOXHWKDWLVQRWWKHQDPHRIDGDWDEDVHREMHFW
$YDOXHSDUDPHWHULQDVWDWHPHQWVWULQJFDQEHSDVVHGDVDFRQVWDQWRUSDVVHGDVDSODFHKROGHU
DWUXQWLPH)RUH[DPSOHWKHIROORZLQJVWDWHPHQWVWULQJSDVVHVDVDFRQVWDQW
char *str = "DELETE FROM CUSTOMER WHERE CUST_NO = 256";

66 INTERBASE 5
UNDERSTANDING THE XSQLDA

,WLVDOVRSRVVLEOHWREXLOGVWULQJVDWUXQWLPHIURPDFRPELQDWLRQRIFRQVWDQWV7KLVPHWKRG
LVXVHIXOIRUVWDWHPHQWVZKHUHWKHYDULDEOHLVQRWDWUXHFRQVWDQWRULWLVDWDEOHRUFROXPQ
QDPHDQGZKHUHWKHVWDWHPHQWLVH[HFXWHGRQO\RQFHLQWKHDSSOLFDWLRQ
7RSDVVDSDUDPHWHUDVDSODFHKROGHUWKHYDOXHLVSDVVHGDVDTXHVWLRQPDUN " HPEHGGHG
ZLWKLQWKHVWDWHPHQWVWULQJ
char *str = "DELETE FROM CUSTOMER WHERE CUST_NO = ?";

:KHQD'64/IXQFWLRQSURFHVVHVDVWDWHPHQWFRQWDLQLQJDSODFHKROGHULWUHSODFHVWKH
TXHVWLRQPDUNZLWKDYDOXHVXSSOLHGLQDQH[WHQGHG64/GHVFULSWRUDUHD ;64/'$ SUHYLRXVO\
GHFODUHGDQGSRSXODWHGLQWKHDSSOLFDWLRQ8VHSODFHKROGHUVLQVWDWHPHQWVWKDWDUHSUHSDUHG
RQFHEXWH[HFXWHGPDQ\WLPHVZLWKGLIIHUHQWSDUDPHWHUYDOXHV
5HSODFHDEOHYDOXHSDUDPHWHUVDUHRIWHQXVHGWRVXSSO\YDOXHVLQ64/6(/(&7VWDWHPHQW
:+(5(FODXVHFRPSDULVRQVDQGLQWKH83'$7(VWDWHPHQW6(7FODXVH

Understanding the XSQLDA

$OO'64/DSSOLFDWLRQVPXVWGHFODUHRQHRUPRUHH[WHQGHG64/GHVFULSWRUDUHDV ;64/'$V 
7KH;64/'$VWUXFWXUHGHILQLWLRQFDQEHIRXQGLQWKHLEDVHKKHDGHUILOHLQWKH,QWHU%DVH
LQFOXGHGLUHFWRU\$SSOLFDWLRQVGHFODUHLQVWDQFHVRIWKH;64/'$IRUXVH
7KH;64/'$LVDKRVWODQJXDJHGDWDVWUXFWXUHWKDW'64/XVHVWRWUDQVSRUWGDWDWRRUIURP
DGDWDEDVHZKHQSURFHVVLQJDQ64/VWDWHPHQWVWULQJ7KHUHDUHWZRW\SHVRI;64/'$VLQSXW
GHVFULSWRUVDQGRXWSXWGHVFULSWRUV%RWKLQSXWDQGRXWSXWGHVFULSWRUVDUHLPSOHPHQWHGXVLQJ
WKH;64/'$VWUXFWXUH
2QHILHOGLQWKH;64/'$VTOYDULVDQ;64/9$5VWUXFWXUH7KHVTOYDULVHVSHFLDOO\LPSRUWDQW
EHFDXVHRQH;64/9$5PXVWEHGHILQHGIRUHDFKLQSXWSDUDPHWHURUFROXPQUHWXUQHG/LNH
WKH;64/'$WKH;64/9$5LVDVWUXFWXUHGHILQHGLQLEDVHKLQWKH,QWHU%DVHLQFOXGHGLUHFWRU\
$SSOLFDWLRQVGRQRWGHFODUHLQVWDQFHVRIWKH;64/9$5DKHDGRIWLPHEXWPXVWLQVWHDG
G\QDPLFDOO\DOORFDWHVWRUDJHIRUWKHSURSHUQXPEHURI;64/9$5VWUXFWXUHVUHTXLUHGIRUHDFK
'64/VWDWHPHQWEHIRUHLWLVH[HFXWHGWKHQGHDOORFDWHLWDVDSSURSULDWHDIWHUVWDWHPHQW
H[HFXWLRQ

API GUIDE 67
 CHAPTER 6 WORKING WITH DYNAMIC SQL

7KHIROORZLQJILJXUHLOOXVWUDWHVWKHUHODWLRQVKLSEHWZHHQWKH;64/'$DQGWKH;64/9$5

Single instance of XSQLDA

short version
char sqldaid[8]
ISC_LONG sqldabc
short sqln
short sqld
XSQLVAR sqlvar[1]

Array of n instances of XSQLVAR

1st instance nth instance
short sqltype short sqltype
short sqlscale short sqlscale
short sqlsubtype short sqlsubtype
short sqllen short sqllen
char *sqldata char *sqldata
short *sqlind short *sqlind
short sqlname_length short sqlname_length
char sqlname[32] char sqlname[32]
short relname_length short relname_length
char relname[32] char relname[32]
short ownname_length short ownname_length
char ownname[32] char ownname[32]
short aliasname_length short aliasname_length
char aliasname[32] char aliasname[32]
$QLQSXW;64/'$FRQVLVWVRIDVLQJOH;64/'$VWUXFWXUHDQGRQH;64/9$5VWUXFWXUHIRU
HDFKLQSXWSDUDPHWHU$QRXWSXW;64/'$DOVRFRQVLVWVRIRQH;64/'$VWUXFWXUHDQGRQH
;64/9$5VWUXFWXUHIRUHDFKGDWDLWHPUHWXUQHGE\WKHVWDWHPHQW$Q;64/'$DQGLWV
DVVRFLDWHG;64/9$5VWUXFWXUHVDUHDOORFDWHGDVDVLQJOHEORFNRIFRQWLJXRXVPHPRU\

68 INTERBASE 5
UNDERSTANDING THE XSQLDA

7KHisc_dsql_prepare(),isc_dsql_describe()DQGisc_dsql_describe_bind()IXQFWLRQV
FDQEHXVHGWRGHWHUPLQHWKHSURSHUQXPEHURI;64/9$5VWUXFWXUHVWRDOORFDWHDQGWKH
;64/'$B/(1*7+PDFURFDQEHXVHGWRDOORFDWHWKHSURSHUDPRXQWRIVSDFH)RUPRUH
LQIRUPDWLRQDERXWWKH;64/'$B/(1*7+PDFURVHH´8VLQJWKH;64/'$B/(1*7+
PDFURµRQSDJH 

XSQLDA field descriptions

7KHIROORZLQJWDEOHGHVFULEHVWKHILHOGVWKDWFRPSULVHWKH;64/'$VWUXFWXUH

Field definition Description

short version Indicates the version of the XSQLDA structure. Set by an application. The current version
is defined in ibase.h as SQLDA_VERSION1
char sqldaid[8] Reserved for future use
ISC_LONG sqldabc Reserved for future use
short sqln Indicates the number of elements in the sqlvar array; the application should set this field
whenever it allocates storage for a descriptor
short sqld Indicates the number of parameters for an input XSQLDA, or the number of select-list
items for an output XSQLDA; set by InterBase during an isc_dsql_describe(),
isc_dsql_describe_bind(), or isc_dsql_prepare()
For an input descriptor, an sqld of 0 indicates that the SQL statement has no parameters;
for an output descriptor, an sqld of 0 indicates that the SQL statement is not a SELECT
statement
XSQLVAR sqlvar The array of XSQLVAR structures; the number of elements in the array is specified in the
sqln field
TABLE 6.2 XSQLDA field descriptions

API GUIDE 69
 CHAPTER 6 WORKING WITH DYNAMIC SQL

7KHIROORZLQJWDEOHGHVFULEHVWKHILHOGVWKDWFRPSULVHWKH;64/9$5VWUXFWXUH

Field definition Description

short sqltype Indicates the SQL datatype of parameters or select-list items; set by InterBase
during isc_dsql_describe(), isc_dsql_describe_bind(), or
isc_dsql_prepare()
short sqlscale Provides scale, specified as a negative number, for exact numeric datatypes
(DECIMAL, NUMERIC); set by InterBase during isc_dsql_describe(),
isc_dsql_describe_bind(), or isc_dsql_prepare()
short sqlsubtype Specifies the subtype for Blob data; set by InterBase during
isc_dsql_describe(), isc_dsql_describe_bind(), or isc_dsql_prepare()
short sqllen Indicates the maximum size, in bytes, of data in the sqldata field; set by
InterBase during isc_dsql_describe(), isc_dsql_describe_bind(), or
isc_dsql_prepare()
char *sqldata For input descriptors, specifies either the address of a select-list item or a
parameter; set by the application
For output descriptors, contains a value for a select-list item; set by InterBase
short *sqlind On input, specifies the address of an indicator variable; set by an application;
on output, specifies the address of column indicator value for a select-list
item following a FETCH
A value of 0 indicates that the column is not NULL; a value of –1 indicates the
column is NULL; set by InterBase
short sqlname_length Specifies the length, in bytes, of the data in field, sqlname; set by InterBase
during isc_dsql_prepare() or isc_dsql_describe()
char sqlname[32] Contains the name of the column. Not NULL (\0) terminated; set by InterBase
during isc_dsql_prepare() or isc_dsql_describe()
short relname_length Specifies the length, in bytes, of the data in field, relname; set by InterBase
during isc_dsql_prepare() or isc_dsql_describe()
TABLE 6.3 XSQLVAR field descriptions

70 INTERBASE 5
UNDERSTANDING THE XSQLDA

Field definition Description

char relname[32] Contains the name of the table; not NULL (\0) terminated, set by InterBase
during isc_dsql_prepare() or isc_dsql_describe()
short ownname_length Specifies the length, in bytes, of the data in field, ownname; set by InterBase
during isc_dsql_prepare() or isc_dsql_describe()
char ownname[32] Contains the name of the table owner; not NULL (\0) terminated, set by
InterBase during isc_dsql_prepare() or isc_dsql_describe()
short aliasname_length Specifies the length, in bytes, of the data in field, aliasname; set by InterBase
during isc_dsql_prepare() or isc_dsql_describe()
char aliasname[32] Contains the alias name of the column. If no alias exists, contains the column
name; not NULL (\0) terminated, set by
InterBase during isc_dsql_prepare() or isc_dsql_describe()
TABLE 6.3 XSQLVAR field descriptions (continued)

Input descriptors
,QSXWGHVFULSWRUVDUHXVHGWRSURFHVV64/VWDWHPHQWVWULQJVWKDWFRQWDLQSDUDPHWHUV%HIRUH
DQDSSOLFDWLRQFDQH[HFXWHDVWDWHPHQWZLWKSDUDPHWHUVLWPXVWVXSSO\YDOXHVIRUWKHP7KH
DSSOLFDWLRQLQGLFDWHVWKHQXPEHURISDUDPHWHUVSDVVHGLQWKH;64/'$VTOGILHOGWKHQ
GHVFULEHVHDFKSDUDPHWHULQDVHSDUDWH;64/9$5VWUXFWXUH)RUH[DPSOHWKHIROORZLQJ
VWDWHPHQWVWULQJFRQWDLQVWZRSDUDPHWHUVVRDQDSSOLFDWLRQPXVWVHWVTOGWRDQGGHVFULEH
HDFKSDUDPHWHU
char *str = "UPDATE DEPARTMENT SET BUDGET = ? WHERE LOCATION = ?";

:KHQWKHVWDWHPHQWLVH[HFXWHGWKHILUVW;64/9$5VXSSOLHVLQIRUPDWLRQDERXWWKH%8'*(7
YDOXHDQGWKHVHFRQG;64/9$5VXSSOLHVWKH/2&$7,21YDOXH
)RUPRUHLQIRUPDWLRQDERXWXVLQJLQSXWGHVFULSWRUVVHH´'64/SURJUDPPLQJPHWKRGVµRQ
SDJH 

Output descriptors
2XWSXWGHVFULSWRUVUHWXUQYDOXHVIURPDQH[HFXWHGTXHU\WRDQDSSOLFDWLRQ7KHVTOGILHOGRI
WKH;64/'$LQGLFDWHVKRZPDQ\YDOXHVZHUHUHWXUQHG(DFKYDOXHLVVWRUHGLQDVHSDUDWH
;64/9$5VWUXFWXUH7KH;64/'$VTOYDUILHOGSRLQWVWRWKHILUVWRIWKHVH;64/9$5VWUXFWXUHV
7KHIROORZLQJVWDWHPHQWVWULQJUHTXLUHVDQRXWSXWGHVFULSWRU

API GUIDE 71
 CHAPTER 6 WORKING WITH DYNAMIC SQL

char *str = "SELECT * FROM CUSTOMER WHERE CUST_NO > 100";

)RULQIRUPDWLRQDERXWUHWULHYLQJLQIRUPDWLRQIURPDQRXWSXWGHVFULSWRUVHH´'64/
SURJUDPPLQJPHWKRGVµRQSDJH 

Using the XSQLDA_LENGTH macro

7KHLEDVHKKHDGHUILOHGHILQHVDPDFUR;64/'$B/(1*7+WRFDOFXODWHWKHQXPEHURIE\WHV
WKDWPXVWEHDOORFDWHGIRUDQLQSXWRURXWSXW;64/'$;64/'$B/(1*7+LVGHILQHGDV
IROORZV
#define XSQLDA_LENGTH (n) (sizeof (XSQLDA) + (n – 1) * sizeof(XSQLVAR))
QLVWKHQXPEHURISDUDPHWHUVLQDVWDWHPHQWVWULQJRUWKHQXPEHURIVHOHFWOLVWLWHPV
UHWXUQHGIURPDTXHU\)RUH[DPSOHWKHIROORZLQJ&VWDWHPHQWXVHVWKH;64/'$B/(1*7+
PDFURWRVSHFLI\KRZPXFKPHPRU\WRDOORFDWHIRUDQ;64/'$ZLWKSDUDPHWHUVRUUHWXUQ
LWHPV
XSQLDA *my_xsqlda;
. . .
my_xsqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(5));
. . .

)RUPRUHLQIRUPDWLRQDERXWXVLQJWKH;64/'$B/(1*7+PDFURVHH´'64/SURJUDPPLQJ
PHWKRGVµRQSDJH 

SQL datatype macro constants

,QWHU%DVHGHILQHVDVHWRIPDFURFRQVWDQWVWRUHSUHVHQW64/GDWDW\SHVDQG18//VWDWXV
LQIRUPDWLRQLQDQ;64/9$5$QDSSOLFDWLRQVKRXOGXVHWKHVHPDFURFRQVWDQWVWRVSHFLI\WKH
GDWDW\SHRISDUDPHWHUVDQGWRGHWHUPLQHWKHGDWDW\SHVRIVHOHFWOLVWLWHPVLQDQ64/
VWDWHPHQW7KHIROORZLQJWDEOHOLVWVHDFK64/GDWDW\SHLWVFRUUHVSRQGLQJPDFURFRQVWDQW
H[SUHVVLRQ&GDWDW\SHRU,QWHU%DVHW\SHGHIDQGZKHWKHURUQRWWKHVTOLQGILHOGLVXVHGWR
LQGLFDWHDSDUDPHWHURUYDULDEOHWKDWFRQWDLQV18//RUXQNQRZQGDWD

sqlind
SQL datatype Macro expression C datatype or typedef used?
Array SQL_ARRAY ISC_QUAD No
Array SQL_ARRAY + 1 ISC_QUAD Yes
Blob SQL_BLOB ISC_QUAD No
TABLE 6.4 SQL datatypes, macro expressions, and C datatypes

72 INTERBASE 5
UNDERSTANDING THE XSQLDA

sqlind
SQL datatype Macro expression C datatype or typedef used?
BLOB SQL_BLOB + 1 ISC_QUAD Yes
CHAR SQL_TEXT char[] No
CHAR SQL_TEXT + 1 char[] Yes
DATE SQL_DATE ISC_QUAD No
DATE SQL_DATE + 1 ISC_QUAD Yes
DECIMAL SQL_SHORT, SQL_LONG, or SQL_DOUBLE int, long, or double No
DECIMAL SQL_SHORT + 1, SQL_LONG + 1, or SQL_DOUBLE + 1 int, long, or double Yes
DOUBLE SQL_DOUBLE double No
PRECISON

DOUBLE SQL_DOUBLE + 1 double Yes

PRECISION

INTEGER SQL_LONG long No

INTEGER SQL_LONG + 1 ISC_LONG Yes
FLOAT SQL_FLOAT float No
FLOAT SQL_FLOAT + 1 float Yes
NUMERIC SQL_SHORT, SQL_LONG, or SQL_DOUBLE int, long, or double No
NUMERIC SQL_SHORT + 1, SQL_LONG + 1, or SQL_DOUBLE + 1 int, long, or double Yes
SMALLINT SQL_SHORT short No
SMALLINT SQL_SHORT + 1 short Yes
VARCHAR SQL_VARYING First 2 bytes: short containing the No
length of the character string;
remaining bytes: char[]
VARCHAR SQL_VARYING + 1 First 2 bytes: short containing the Yes
length of the character string;
remaining bytes: char[]
TABLE 6.4 SQL datatypes, macro expressions, and C datatypes (continued)

API GUIDE 73
 CHAPTER 6 WORKING WITH DYNAMIC SQL

Note '(&,0$/DQG180(5,&GDWDW\SHVDUHVWRUHGLQWHUQDOO\DV60$//,17,17(*(5RU
'28%/(35(&,6,21GDWDW\SHV7RVSHFLI\WKHFRUUHFWPDFURH[SUHVVLRQWRSURYLGHIRUD
'(&,0$/RU180(5,&FROXPQXVHisqlWRH[DPLQHWKHFROXPQGHILQLWLRQLQWKHWDEOHWRVHH
KRZ,QWHU%DVHLVVWRULQJFROXPQGDWDWKHQFKRRVHDFRUUHVSRQGLQJPDFURH[SUHVVLRQ
7KHGDWDW\SHLQIRUPDWLRQIRUDSDUDPHWHURUVHOHFWOLVWLWHPLVFRQWDLQHGLQWKHVTOW\SHILHOGRI
WKH;64/9$5VWUXFWXUH7KHYDOXHFRQWDLQHGLQVTOW\SHSURYLGHVWZRSLHFHVRILQIRUPDWLRQ
g 7KHGDWDW\SHRIWKHSDUDPHWHURUVHOHFWOLVWLWHP
g :KHWKHUVTOLQGLVXVHGWRLQGLFDWH18//YDOXHV,IVTOLQGLVXVHGLWVYDOXHVSHFLILHVZKHWKHUWKH
SDUDPHWHURUVHOHFWOLVWLWHPLV18// ² RUQRW18//  
)RUH[DPSOHLIVTOW\SHHTXDOV64/B7(;7WKHSDUDPHWHURUVHOHFWOLVWLWHPLVD&+$5WKDWGRHV
QRWXVHVTOLQGWRFKHFNIRUD18//YDOXH EHFDXVHLQWKHRU\18//YDOXHVDUHQRWDOORZHGIRU
LW ,IVTOW\SHHTXDOV64/B7(;7WKHQVTOLQGFDQEHFKHFNHGWRVHHLIWKHSDUDPHWHURU
VHOHFWOLVWLWHPLV18//

7,3 7KH&ODQJXDJHH[SUHVVLRQVTOW\SH SURYLGHVDXVHIXOWHVWRIZKHWKHUDSDUDPHWHURU

VHOHFWOLVWLWHPFDQFRQWDLQD18//7KHH[SUHVVLRQHYDOXDWHVWRLIWKHSDUDPHWHURU
VHOHFWOLVWLWHPFDQQRWFRQWDLQD18//DQGLIWKHSDUDPHWHURUVHOHFWOLVWLWHPFDQFRQWDLQ
D18//7KHIROORZLQJFRGHIUDJPHQWGHPRQVWUDWHVKRZWRXVHWKHH[SUHVVLRQ
if (sqltype & 1 == 0)
{
/* parameter or select-list item that CANNOT contain a NULL */
}
else
{
/* parameter or select-list item CAN contain a NULL */
}

%\GHIDXOWERWKisc_dsql_prepare()DQGisc_dsql_describe()UHWXUQDPDFURH[SUHVVLRQRI
W\SHVRVTOLQGVKRXOGDOZD\VEHH[DPLQHGIRU18//YDOXHVZLWKWKHVHVWDWHPHQWV

Handling varying string datatypes

9$5&+$5&+$5$&7(59$5<,1*DQG1&+$59$5<,1*GDWDW\SHVUHTXLUHFDUHIXOKDQGOLQJ
LQ'64/7KHILUVWWZRE\WHVRIWKHVHGDWDW\SHVFRQWDLQVWULQJOHQJWKLQIRUPDWLRQZKLOHWKH
UHPDLQGHURIWKHGDWDFRQWDLQVWKHDFWXDOE\WHVRIVWULQJGDWDWRSURFHVV
7RDYRLGKDYLQJWRZULWHFRGHWRH[WUDFWDQGSURFHVVYDULDEOHOHQJWKVWULQJVLQDQDSSOLFDWLRQ
LWLVSRVVLEOHWRIRUFHWKHVHGDWDW\SHVWRIL[HGOHQJWKXVLQJ64/PDFURH[SUHVVLRQV)RUPRUH
LQIRUPDWLRQDERXWIRUFLQJYDULDEOHOHQJWKGDWDWRIL[HGOHQJWKIRUSURFHVVLQJVHH´&RHUFLQJ
GDWDW\SHVµRQSDJH 

74 INTERBASE 5
UNDERSTANDING THE XSQLDA

$SSOLFDWLRQVFDQLQVWHDGGHWHFWDQGSURFHVVYDULDEOHOHQJWKGDWDGLUHFWO\7RGRVRWKH\PXVW
H[WUDFWWKHILUVWWZRE\WHVIURPWKHVWULQJWRGHWHUPLQHWKHE\WHOHQJWKRIWKHVWULQJLWVHOI
WKHQUHDGWKHVWULQJE\WHE\E\WHLQWRDQXOOWHUPLQDWHGEXIIHU

Handling NUMERIC and DECIMAL datatypes

'(&,0$/DQG180(5,&GDWDW\SHVDUHVWRUHGLQWHUQDOO\DV60$//,17,17(*(5RU
'28%/(35(&,6,21GDWDW\SHVGHSHQGLQJRQWKHSUHFLVLRQDQGVFDOHGHILQHGIRUDFROXPQ
GHILQLWLRQWKDWXVHVWKHVHW\SHV7RGHWHUPLQHKRZD'(&,0$/RU180(5,&YDOXHLVDFWXDOO\
VWRUHGLQWKHGDWDEDVHXVHisqlWRH[DPLQHWKHFROXPQGHILQLWLRQLQWKHWDEOH,I180(5,&LV
UHSRUWHGWKHQGDWDLVDFWXDOO\EHLQJVWRUHGDV'28%/(35(&,6,21
:KHQD'(&,0$/RU180(5,&YDOXHLVVWRUHGDVD60$//,17RU,17(*(5WKHYDOXHLV
VWRUHGDVDZKROHQXPEHU'XULQJUHWULHYDOLQ'64/WKHVTOVFDOHILHOGRIWKH;64/9$5LVVHW
WRDQHJDWLYHQXPEHUWKDWLQGLFDWHVWKHIDFWRURIE\ZKLFKWKHZKROHQXPEHU UHWXUQHGLQ
VTOGDWD PXVWEHGLYLGHGLQRUGHUWRSURGXFHWKHFRUUHFW180(5,&RU'(&,0$/YDOXHZLWK
LWVIUDFWLRQDOSDUW,IVTOFDOHLV²WKHQWKHQXPEHUPXVWEHGLYLGHGE\LILWLV²WKHQWKH
QXPEHUPXVWEHGLYLGHGE\
²E\DQGVRIRUWK

Coercing datatypes
6RPHWLPHVZKHQSURFHVVLQJ'64/LQSXWSDUDPHWHUVDQGVHOHFWOLVWLWHPVLWLVGHVLUDEOHRU
QHFHVVDU\WRWUDQVODWHRQHGDWDW\SHWRDQRWKHU7KLVSURFHVVLVUHIHUUHGWRDVGDWDW\SHFRHUFLRQ
)RUH[DPSOHGDWDW\SHFRHUFLRQLVRIWHQXVHGZKHQSDUDPHWHUVRUVHOHFWOLVWLWHPVDUHRIW\SH
9$5&+$57KHILUVWWZRE\WHVRI9$5&+$5GDWDFRQWDLQVWULQJOHQJWKLQIRUPDWLRQZKLOHWKH
UHPDLQGHURIWKHGDWDLVWKHVWULQJWRSURFHVV%\FRHUFLQJWKHGDWDIURP64/B9$5<,1*WR
64/B7(;7GDWDSURFHVVLQJFDQEHVLPSOLILHG
&RHUFLRQFDQRQO\EHIURPRQHFRPSDWLEOHGDWDW\SHWRDQRWKHU)RUH[DPSOH64/B9$5<,1*
WR64/B7(;7RU64/B6+257WR64/B/21*

4 &RHUFLQJFKDUDFWHUGDWDW\SHV
7RFRHUFH64/B9$5<,1*GDWDW\SHVWR64/B7(;7GDWDW\SHVFKDQJHWKHVTOW\SHILHOGLQWKH
SDUDPHWHU·VRUVHOHFWOLVWLWHP·V;64/9$5VWUXFWXUHWRWKHGHVLUHG64/PDFURGDWDW\SH
FRQVWDQW)RUH[DPSOHWKHIROORZLQJVWDWHPHQWDVVXPHVWKDWYDULVDSRLQWHUWRDQ;64/9$5
VWUXFWXUHDQGWKDWLWFRQWDLQVDQ64/B9$5<,1*GDWDW\SHWRFRQYHUWWR64/B7(;7
var->sqltype = SQL_TEXT;

API GUIDE 75
 CHAPTER 6 WORKING WITH DYNAMIC SQL

$IWHUFRHUFLQJDFKDUDFWHUGDWDW\SHSURYLGHSURSHUVWRUDJHVSDFHIRULW7KH;64/9$5ILHOG
VTOOHQFRQWDLQVLQIRUPDWLRQDERXWWKHVL]HRIWKHXQFRHUFHGGDWD
6HWWKH;64/9$5VTOGDWDILHOGWRWKHDGGUHVVRIWKHGDWD

4 &RHUFLQJQXPHULFGDWDW\SHV
7RFRHUFHRQHQXPHULFGDWDW\SHWRDQRWKHUFKDQJHWKHVTOW\SHILHOGLQWKHSDUDPHWHU·VRU
VHOHFWOLVWLWHP·V;64/9$5VWUXFWXUHWRWKHGHVLUHG64/PDFURGDWDW\SHFRQVWDQW)RU
H[DPSOHWKHIROORZLQJVWDWHPHQWDVVXPHVWKDWYDULVDSRLQWHUWRDQ;64/9$5VWUXFWXUHDQG
WKDWLWFRQWDLQVDQ64/B6+257GDWDW\SHWRFRQYHUWWR64/B/21*
var->sqltype = SQL_LONG;

,03257$17 'RQRWFRHUFHDODUJHUGDWDW\SHWRDVPDOOHURQH'DWDFDQEHORVWLQVXFKDWUDQVODWLRQ

4 6HWWLQJD18//LQGLFDWRU
,IDSDUDPHWHURUVHOHFWOLVWLWHPFRQWDLQVD18//YDOXHWKHVTOLQGILHOGVKRXOGEHXVHGWR
LQGLFDWHLWV18//VWDWXV$SSURSULDWHVWRUDJHVSDFHPXVWEHDOORFDWHGIRUVTOLQGEHIRUHYDOXHV
FDQEHVWRUHGWKHUH
%HIRUHLQVHUWLRQVHWVTOLQGWR²WRLQGLFDWHWKDW18//YDOXHVDUHOHJDO2WKHUZLVHVHWVTOLQG
WR
$IWHUVHOHFWLRQDQVTOLQGRI²LQGLFDWHVDILHOGFRQWDLQVD18//YDOXH2WKHUYDOXHVLQGLFDWH
DILHOGFRQWDLQVQRQ18//GDWD

Aligning numerical data

2UGLQDULO\ZKHQDYDULDEOHZLWKDQXPHULFGDWDW\SHLVFUHDWHGWKHFRPSLOHUZLOOHQVXUHWKDW
WKHYDULDEOHLVVWRUHGDWDSURSHUO\DOLJQHGDGGUHVVEXWZKHQQXPHULFGDWDLVVWRUHGLQD
G\QDPLFDOO\DOORFDWHGEXIIHUVSDFHVXFKDVFDQEHSRLQWHGWRE\WKH;64/'$DQG;64/9$5
VWUXFWXUHVWKHSURJUDPPHUPXVWWDNHSUHFDXWLRQVWRHQVXUHWKDWWKHVWRUDJHVSDFHLVSURSHUO\
DOLJQHG
&HUWDLQSODWIRUPVLQSDUWLFXODUWKRVHZLWK5,6&SURFHVVRUVUHTXLUHWKDWQXPHULFDOGDWDLQ
G\QDPLFDOO\DOORFDWHGVWRUDJHVWUXFWXUHVEHDOLJQHGSURSHUO\LQPHPRU\$OLJQPHQWLV
GHSHQGHQWERWKRQGDWDW\SHDQGSODWIRUP
)RUH[DPSOHDVKRUWLQWHJHURQD6XQ63$5&VWDWLRQPXVWEHORFDWHGDWDQDGGUHVVGLYLVLEOH
E\ZKLOHDORQJRQWKHVDPHSODWIRUPPXVWEHORFDWHGDWDQDGGUHVVGLYLVLEOHE\,QPRVW
FDVHVDGDWDLWHPLVSURSHUO\DOLJQHGLIWKHDGGUHVVRILWVVWDUWLQJE\WHLVGLYLVLEOHE\WKHFRUUHFW
DOLJQPHQWQXPEHU&RQVXOWVSHFLILFV\VWHPDQGFRPSLOHUGRFXPHQWDWLRQIRUDOLJQPHQW
UHTXLUHPHQWV

76 INTERBASE 5
DSQL PROGRAMMING METHODS

$XVHIXOUXOHRIWKXPELVWKDWWKHVL]HRIDGDWDW\SHLVDOZD\VDYDOLGDOLJQPHQWQXPEHUIRU
WKHGDWDW\SH)RUDJLYHQW\SH7LIVL]HRI 7 HTXDOVQWKHQDGGUHVVHVGLYLVLEOHE\QDUH
FRUUHFWO\DOLJQHGIRU77KHIROORZLQJPDFURH[SUHVVLRQFDQEHXVHGWRDOLJQGDWD
#define ALIGN(ptr, n) ((ptr + n - 1) & ~(n - 1))

ZKHUHSWULVDSRLQWHUWRFKDU
7KHIROORZLQJFRGHLOOXVWUDWHVKRZWKH$/,*1PDFURPLJKWEHXVHG
char *buffer_pointer, *next_aligned;
next_aligned = ALIGN(buffer_pointer, sizeof(T));

DSQL programming methods

7KHUHDUHIRXUSRVVLEOH'64/SURJUDPPLQJPHWKRGVIRUKDQGOLQJDQ64/VWDWHPHQWVWULQJ
7KHEHVWPHWKRGIRUSURFHVVLQJDVWULQJGHSHQGVRQWKHW\SHRI64/VWDWHPHQWLQWKHVWULQJ
DQGZKHWKHURUQRWLWFRQWDLQVSODFHKROGHUVIRUSDUDPHWHUV7KHIROORZLQJGHFLVLRQWDEOH
H[SODLQVKRZWRGHWHUPLQHWKHDSSURSULDWHSURFHVVLQJPHWKRGIRUDJLYHQVWULQJ

Is it a query? Does it have placeholders? Processing method to use:

No No Method 1
No Yes Method 2
Yes No Method 3
Yes Yes Method 4
TABLE 6.5 SQL statement strings and recommended processing methods

Method 1: Non-query statements without parameters

7KHUHDUHWZRZD\VWRSURFHVVDQ64/VWDWHPHQWVWULQJFRQWDLQLQJDQRQTXHU\VWDWHPHQW
ZLWKRXWSODFHKROGHUSDUDPHWHUV
g 8VHisc_dsql_execute_immediate()WRSUHSDUHDQGH[HFXWHWKHVWULQJDVLQJOHWLPH
g 8VHisc_dsql_allocate_statement()WRDOORFDWHDVWDWHPHQWVWULQJIRUWKHVWDWHPHQWWR
H[HFXWHisc_dsql_prepare()WRSDUVHWKHVWDWHPHQWIRUH[HFXWLRQDQGDVVLJQLWDQDPHWKHQ
XVHisc_dsql_execute()WRFDUU\RXWWKHVWDWHPHQW·VDFWLRQVDVPDQ\WLPHVDVUHTXLUHGLQDQ
DSSOLFDWLRQ

API GUIDE 77
 CHAPTER 6 WORKING WITH DYNAMIC SQL

4 8VLQJLVFBGVTOBH[HFXWHBLPPHGLDWH 
 7RH[HFXWHDVWDWHPHQWVWULQJDVLQJOHWLPHXVH
isc_dsql_execute_immediate()
 (OLFLWDVWDWHPHQWVWULQJIURPWKHXVHURUFUHDWHRQHWKDWFRQWDLQVWKH64/
VWDWHPHQWWREHSURFHVVHG)RUH[DPSOHWKHIROORZLQJVWDWHPHQWFUHDWHVDQ64/
VWDWHPHQWVWULQJ
char *str = "UPDATE DEPARTMENT SET BUDGET = BUDGET * 1.05";

 3DUVHDQGH[HFXWHWKHVWDWHPHQWVWULQJXVLQJisc_dsql_execute_immediate()
isc_dsql_execute_immediate(status_vector, &db1, &trans, 0, str, 1, NULL);
Note isc_dsql_execute_immediate()DOVRDFFHSWVVWULQJOLWHUDOV)RUH[DPSOH
isc_dsql_execute_immediate(status_vector, &db1, &trans, 0,
"UPDATE DEPARTMENT SET BUDGET = BUDGET * 1.05", 1, NULL);

)RUWKHFRPSOHWHV\QWD[RIisc_dsq_execute_immediate()DQGDQH[SODQDWLRQRILWV
SDUDPHWHUVVHH&KDSWHU´$3,)XQFWLRQ5HIHUHQFHµ

4 8VLQJLVFBGVTOBSUHSDUH  DQGLVFBGVTOBH[HFXWH 
7RH[HFXWHDVWDWHPHQWVWULQJVHYHUDOWLPHVXVHisc_dsql_allocate_statement()
isc_dsql_prepare()DQGisc_dsql_execute()
 (OLFLWDVWDWHPHQWVWULQJIURPWKHXVHURUFUHDWHRQHWKDWFRQWDLQVWKH64/
VWDWHPHQWWREHSURFHVVHG)RUH[DPSOHWKHIROORZLQJVWDWHPHQWFUHDWHVDQ64/
VWDWHPHQWVWULQJ
char *str = "UPDATE DEPARTMENT SET BUDGET = BUDGET * 1.05";

 'HFODUHDQGLQLWLDOL]HDQ64/VWDWHPHQWKDQGOHWKHQDOORFDWHLWZLWK
isc_dsql_allocate_statement()
isc_stmt_handle stmt; /* Declare a statement handle. */
stmt = NULL; /* Set handle to NULL before allocation. */
. . .
isc_dsql_allocate_statement(status_vector, &db1, &stmt);

 3DUVHWKHVWDWHPHQWVWULQJZLWKisc_dsql_prepare()7KLVVHWVWKHVWDWHPHQW
KDQGOH VWPW WRUHIHUWRWKHSDUVHGIRUPDW7KHVWDWHPHQWKDQGOHLVXVHGLQ
VXEVHTXHQWFDOOVWRisc_dsql_execute()
isc_dsql_prepare(status_vector, &trans, &stmt, 0, str, 1, NULL);
Note isc_dsql_prepare()DOVRDFFHSWVVWULQJOLWHUDOV)RUH[DPSOH
isc_dsql_prepare(status_vector, &trans, &stmt, 0,
"UPDATE DEPARTMENT SET BUDGET = BUDGET * 1.05", 1, NULL);

78 INTERBASE 5
DSQL PROGRAMMING METHODS

 ([HFXWHWKHQDPHGVWDWHPHQWVWULQJXVLQJisc_dsql_execute())RUH[DPSOH
WKHIROORZLQJVWDWHPHQWH[HFXWHVDVWDWHPHQWVWULQJQDPHGVWPW
isc_dsql_execute(status_vector, &trans, &stmt, 1, NULL);

2QFHDVWDWHPHQWVWULQJLVSUHSDUHGLWFDQEHH[HFXWHGDVPDQ\WLPHVDVUHTXLUHGLQDQ
DSSOLFDWLRQ

Method 2: Non-query statements with parameters

7KHUHDUHWZRVWHSVWRSURFHVVLQJDQ64/VWDWHPHQWVWULQJFRQWDLQLQJDQRQTXHU\VWDWHPHQW
ZLWKSODFHKROGHUSDUDPHWHUV
 &UHDWHDQLQSXW;64/'$WRSURFHVVDVWDWHPHQWVWULQJ·VSDUDPHWHUV
 3UHSDUHDQGH[HFXWHWKHVWDWHPHQWVWULQJZLWKLWVSDUDPHWHUV

4 &UHDWLQJWKHLQSXW;64/'$
3ODFHKROGHUSDUDPHWHUVDUHUHSODFHGZLWKDFWXDOGDWDEHIRUHDSUHSDUHG64/VWDWHPHQWVWULQJ
LVH[HFXWHG%HFDXVHWKRVHSDUDPHWHUVDUHXQNQRZQZKHQWKHVWDWHPHQWVWULQJLVFUHDWHGDQ
LQSXW;64/'$PXVWEHFUHDWHGWRVXSSO\SDUDPHWHUYDOXHVDWH[HFXWHWLPH7RSUHSDUHWKH
;64/'$IROORZWKHVHVWHSV
 'HFODUHDYDULDEOHWRKROGWKH;64/'$QHHGHGWRSURFHVVSDUDPHWHUV)RU
H[DPSOHWKHIROORZLQJGHFODUDWLRQFUHDWHVDQ;64/'$FDOOHGLQBVTOGD
XSQLDA *in_sqlda;
 2SWLRQDOO\GHFODUHDYDULDEOHIRUDFFHVVLQJWKH;64/9$5VWUXFWXUHRIWKH
;64/'$
XSQLVAR *var;

'HFODULQJDSRLQWHUWRWKH;64/9$5VWUXFWXUHLVQRWQHFHVVDU\EXWFDQVLPSOLI\
UHIHUHQFLQJWKHVWUXFWXUHLQVXEVHTXHQWVWDWHPHQWV
 $OORFDWHPHPRU\IRUWKH;64/'$XVLQJWKH;64/'$B/(1*7+PDFUR7KH
IROORZLQJVWDWHPHQWDOORFDWHVVWRUDJHIRULQBVTOGD
in_sqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(10));

,QWKLVVWDWHPHQWVSDFHIRU;64/9$5VWUXFWXUHVLVDOORFDWHGDOORZLQJWKH;64/'$WR
DFFRPPRGDWHXSWRSDUDPHWHUV
 6HWWKHYHUVLRQILHOGRIWKH;64/'$WR64/'$B9(56,21DQGVHWWKHVTOQILHOGWR
LQGLFDWHWKHQXPEHURI;64/9$5VWUXFWXUHVDOORFDWHG
in_sqlda->version = SQLDA_VERSION1;
in_sqlda->sqln = 10;

API GUIDE 79
 CHAPTER 6 WORKING WITH DYNAMIC SQL

4 3UHSDULQJDQGH[HFXWLQJDVWDWHPHQWVWULQJZLWKSDUDPHWHUV
$IWHUDQ;64/'$LVFUHDWHGIRUKROGLQJDVWDWHPHQWVWULQJ·VSDUDPHWHUVWKHVWDWHPHQWVWULQJ
FDQEHFUHDWHGDQGSUHSDUHG/RFDOYDULDEOHVFRUUHVSRQGLQJWRWKHSODFHKROGHUSDUDPHWHUVLQ
WKHVWULQJPXVWEHDVVLJQHGWRWKHLUFRUUHVSRQGLQJVTOGDWDILHOGVLQWKH;64/9$5VWUXFWXUHV
7RSUHSDUHDQGH[HFXWHDQRQTXHU\VWDWHPHQWVWULQJZLWKSDUDPHWHUVIROORZWKHVHVWHSV
 (OLFLWDVWDWHPHQWVWULQJIURPWKHXVHURUFUHDWHRQHWKDWFRQWDLQVWKH64/
VWDWHPHQWWREHSURFHVVHG)RUH[DPSOHWKHIROORZLQJVWDWHPHQWFUHDWHVDQ64/
VWDWHPHQWVWULQJZLWKSODFHKROGHUSDUDPHWHUV
char *str = "UPDATE DEPARTMENT SET BUDGET = ?, LOCATION = ?";

7KLVVWDWHPHQWVWULQJFRQWDLQVWZRSDUDPHWHUVDYDOXHWREHDVVLJQHGWRWKH%8'*(7
FROXPQDQGDYDOXHWREHDVVLJQHGWRWKH/2&$7,21FROXPQ
 'HFODUHDQGLQLWLDOL]HDQ64/VWDWHPHQWKDQGOHWKHQDOORFDWHLWZLWK
isc_dsql_allocate()
isc_stmt_handle stmt; /* Declare a statement handle. */
stmt = NULL; /* Set handle to NULL before allocation. */
. . .
isc_dsql_allocate_statement(status_vector, &db1, &stmt);

 3DUVHWKHVWDWHPHQWVWULQJZLWKisc_dsql_prepare()7KLVVHWVWKHVWDWHPHQW
KDQGOH VWPW WRUHIHUWRWKHSDUVHGIRUPDW7KHVWDWHPHQWKDQGOHLVXVHGLQ
VXEVHTXHQWFDOOVWRisc_dsql_describe_bind()DQGisc_dsql_execute()
isc_dsql_prepare(status_vector, &trans, &stmt, 0, str, 1, in_sqlda);

 8VHisc_dsql_describe_bind()WRILOOWKHLQSXW;64/'$ZLWKLQIRUPDWLRQ
DERXWWKHSDUDPHWHUVFRQWDLQHGLQWKH64/VWDWHPHQW
isc_dsql_decribe_bind(status_vector, &stmt, 1, in_sqlda);

 &RPSDUHWKHYDOXHRIWKHVTOQILHOGRIWKH;64/'$WRWKHYDOXHRIWKHVTOGILHOG
WRPDNHVXUHHQRXJK;64/9$5VDUHDOORFDWHGWRKROGLQIRUPDWLRQDERXWHDFK
SDUDPHWHUVTOQVKRXOGEHDWOHDVWDVODUJHDVVTOG,IQRWIUHHWKHVWRUDJH
SUHYLRXVO\DOORFDWHGWRWKHLQSXWGHVFULSWRUUHDOORFDWHVWRUDJHWRUHIOHFWWKH
QXPEHURISDUDPHWHUVVSHFLILHGE\VTOGUHVHWVTOQDQGYHUVLRQWKHQH[HFXWH
isc_dsql_describe_bind()DJDLQ
if (in_sqlda->sqld > in_sqlda->sqln)
{
n = in_sqlda->sqld;
free(in_sqlda);
in_sqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(n));
in_sqlda->sqln = n
in_sqlda->version = SQLDA_VERSION1;

80 INTERBASE 5
DSQL PROGRAMMING METHODS

isc_dsql_describe_bind(status_vector, &stmt, 1, in_sqlda);

}

 3URFHVVHDFK;64/9$5SDUDPHWHUVWUXFWXUHLQWKH;64/'$3URFHVVLQJD
SDUDPHWHUVWUXFWXUHLQYROYHVXSWRIRXUVWHSV
 &RHUFHDSDUDPHWHU·VGDWDW\SH RSWLRQDO 
 $OORFDWHORFDOVWRUDJHIRUWKHGDWDSRLQWHGWRE\WKHVTOGDWDILHOGRIWKH;64/9$57KLV
VWHSLVRQO\UHTXLUHGLIVSDFHIRUORFDOYDULDEOHVLVQRWDOORFDWHGXQWLOUXQWLPH7KH
IROORZLQJH[DPSOHLOOXVWUDWHVG\QDPLFDOORFDWLRQRIORFDOYDULDEOHVWRUDJHVSDFH
 3URYLGHDYDOXHIRUWKHSDUDPHWHUFRQVLVWHQWZLWKLWVGDWDW\SH UHTXLUHG 
 3URYLGHD18//YDOXHLQGLFDWRUIRUWKHSDUDPHWHU
7KHIROORZLQJFRGHH[DPSOHLOOXVWUDWHVWKHVHVWHSVORRSLQJWKURXJKHDFK;64/9$5
VWUXFWXUHLQWKHLQBVTOGD;64/'$
for (i=0, var = in_sqlda->sqlvar; i < in_sqlda->sqld; i++, var++)
{
/* Process each XSQLVAR parameter structure here.
Var points to the parameter structure. */

dtype = (var->sqltype & ~1) /* drop NULL flag for now */

switch(dtype)
{
case SQL_VARYING: /* coerce to SQL_TEXT */
var->sqltype = SQL_TEXT;
/* allocate local variable storage */
var->sqldata = (char *)malloc(sizeof(char)*var->sqllen);
. . .
break;
case SQL_TEXT:
var->sqldata = (char *)malloc(sizeof(char)*var->sqllen);
/* provide a value for the parameter */
. . .
break;
case SQL_LONG:
var->sqldata = (char *)malloc(sizeof(long));
/* provide a value for the parameter */
*(long *)(var->sqldata) = 17;
break;
. . .
} /* end of switch statement */
if (sqltype & 1)
{

API GUIDE 81
 CHAPTER 6 WORKING WITH DYNAMIC SQL

/* allocate variable to hold NULL status */

var->sqlind = (short *)malloc(sizeof(short));
}
} /* end of for loop */

)RUPRUHLQIRUPDWLRQDERXWGDWDW\SHFRHUFLRQDQG18//LQGLFDWRUVVHH´&RHUFLQJ
GDWDW\SHVµRQSDJH 
 ([HFXWHWKHQDPHGVWDWHPHQWVWULQJZLWKisc_dsql_execute())RUH[DPSOHWKH
IROORZLQJVWDWHPHQWH[HFXWHVDVWDWHPHQWVWULQJQDPHGVWPW
isc_dsql_execute(status_vector, &trans, &stmt, 1, in_sqlda);

4 5HH[HFXWLQJWKHVWDWHPHQWVWULQJ
2QFHDQRQTXHU\VWDWHPHQWVWULQJZLWKSDUDPHWHUVLVSUHSDUHGLWFDQEHH[HFXWHGDVRIWHQ
DVUHTXLUHGLQDQDSSOLFDWLRQ%HIRUHHDFKVXEVHTXHQWH[HFXWLRQWKHLQSXW;64/'$FDQEH
VXSSOLHGZLWKQHZSDUDPHWHUDQG18//LQGLFDWRUGDWD
7RVXSSO\QHZSDUDPHWHUDQG18//LQGLFDWRUGDWDIRUDSUHSDUHGVWDWHPHQWUHSHDWVWHSRI
´3UHSDULQJDQGH[HFXWLQJDVWDWHPHQWVWULQJZLWKSDUDPHWHUVµRQSDJH 

Method 3: Query statements without parameters

7KHUHDUHWKUHHVWHSVWRSURFHVVLQJDQ64/TXHU\VWDWHPHQWVWULQJZLWKRXWSDUDPHWHUV
 3UHSDUHDQRXWSXW;64/'$WRSURFHVVWKHVHOHFWOLVWLWHPVUHWXUQHGZKHQWKH
TXHU\LVH[HFXWHG
 3UHSDUHWKHVWDWHPHQWVWULQJ
 8VHDFXUVRUWRH[HFXWHWKHVWDWHPHQWDQGUHWULHYHVHOHFWOLVWLWHPVIURPWKH
RXWSXW;64/'$

4 3UHSDULQJWKHRXWSXW;64/'$
0RVWTXHULHVUHWXUQRQHRUPRUHURZVRIGDWDUHIHUUHGWRDVDVHOHFWOLVW%HFDXVHWKHQXPEHU
DQGNLQGRILWHPVUHWXUQHGDUHXQNQRZQZKHQDVWDWHPHQWVWULQJLVFUHDWHGDQRXWSXW
;64/'$PXVWEHFUHDWHGWRVWRUHVHOHFWOLVWLWHPVWKDWDUHUHWXUQHGDWUXQWLPH7RSUHSDUH
WKH;64/'$IROORZWKHVHVWHSV
 'HFODUHDYDULDEOHWRKROGWKH;64/'$QHHGHGWRVWRUHWKHFROXPQGDWDIRUHDFK
URZWKDWZLOOEHIHWFKHG)RUH[DPSOHWKHIROORZLQJGHFODUDWLRQFUHDWHVDQ
;64/'$FDOOHGRXWBVTOGD
XSQLDA *out_sqlda;

82 INTERBASE 5
DSQL PROGRAMMING METHODS

 2SWLRQDOO\GHFODUHDYDULDEOHIRUDFFHVVLQJWKH;64/9$5VWUXFWXUHRIWKH
;64/'$
XSQLVAR *var;

'HFODULQJDSRLQWHUWRWKH;64/9$5VWUXFWXUHLVQRWQHFHVVDU\EXWFDQVLPSOLI\
UHIHUHQFLQJWKHVWUXFWXUHLQVXEVHTXHQWVWDWHPHQWV
 $OORFDWHPHPRU\IRUWKH;64/'$XVLQJWKH;64/'$B/(1*7+PDFUR7KH
IROORZLQJVWDWHPHQWDOORFDWHVVWRUDJHIRURXWBVTOGD
out_sqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(10));

6SDFHIRU;64/9$5VWUXFWXUHVLVDOORFDWHGLQWKLVVWDWHPHQWHQDEOLQJWKH;64/'$WR
DFFRPPRGDWHXSWRVHOHFWOLVWLWHPV
 6HWWKHYHUVLRQILHOGRIWKH;64/'$WR64/'$B9(56,21DQGVHWWKHVTOQILHOG
RIWKH;64/'$WRLQGLFDWHWKHQXPEHURI;64/9$5VWUXFWXUHVDOORFDWHG
out_sqlda->version = SQLDA_VERSION1;
out_sqlda->sqln = 10;

4 3UHSDULQJDTXHU\VWDWHPHQWVWULQJZLWKRXWSDUDPHWHUV
$IWHUDQ;64/'$LVFUHDWHGIRUKROGLQJWKHLWHPVUHWXUQHGE\DTXHU\VWDWHPHQWVWULQJWKH
VWDWHPHQWVWULQJFDQEHFUHDWHGSUHSDUHGDQGGHVFULEHG:KHQDVWDWHPHQWVWULQJLV
H[HFXWHG,QWHU%DVHFUHDWHVWKHVHOHFWOLVWRIVHOHFWHGURZV
7RSUHSDUHDTXHU\VWDWHPHQWVWULQJIROORZWKHVHVWHSV
 (OLFLWDVWDWHPHQWVWULQJIURPWKHXVHURUFUHDWHRQHWKDWFRQWDLQVWKH64/
VWDWHPHQWWREHSURFHVVHG)RUH[DPSOHWKHIROORZLQJVWDWHPHQWFUHDWHVDQ64/
VWDWHPHQWVWULQJWKDWSHUIRUPVDTXHU\
char *str = "SELECT * FROM CUSTOMER";

7KHVWDWHPHQWDSSHDUVWRKDYHRQO\RQHVHOHFWOLVWLWHP 7KHDVWHULVNLVDZLOGFDUG
V\PEROWKDWVWDQGVIRUDOORIWKHFROXPQVLQWKHWDEOHVRWKHDFWXDOQXPEHURILWHPV
UHWXUQHGHTXDOVWKHQXPEHURIFROXPQVLQWKHWDEOH
 'HFODUHDQGLQLWLDOL]HDQ64/VWDWHPHQWKDQGOHWKHQDOORFDWHLWZLWK
isc_dsql_allocate()
isc_stmt_handle stmt; /* Declare a statement handle. */
stmt = NULL; /* Set handle to NULL before allocation. */
. . .
isc_dsql_allocate_statement(status_vector, &db1, &stmt);

API GUIDE 83
 CHAPTER 6 WORKING WITH DYNAMIC SQL

 3DUVHWKHVWDWHPHQWVWULQJZLWKisc_dsql_prepare()7KLVVHWVWKHVWDWHPHQW
KDQGOH VWPW WRUHIHUWRWKHSDUVHGIRUPDW7KHVWDWHPHQWKDQGOHLVXVHGLQ
VXEVHTXHQWFDOOVWRVWDWHPHQWVVXFKDVisc_dsql_describe()DQG
isc_dsql_execute()
isc_dsql_prepare(status_vector, &trans, &stmt, 0, str, 1, NULL);
 8VHisc_dsql_describe()WRILOOWKHRXWSXW;64/'$ZLWKLQIRUPDWLRQDERXWWKH
VHOHFWOLVWLWHPVUHWXUQHGE\WKHVWDWHPHQW
isc_dsql_describe(status_vector, &trans, &stmt, out_sqlda);

 &RPSDUHWKHVTOQILHOGRIWKH;64/'$WRWKHVTOGILHOGWRGHWHUPLQHLIWKHRXWSXW
GHVFULSWRUFDQDFFRPPRGDWHWKHQXPEHURIVHOHFWOLVWLWHPVVSHFLILHGLQWKH
VWDWHPHQW,IQRWIUHHWKHVWRUDJHSUHYLRXVO\DOORFDWHGWRWKHRXWSXWGHVFULSWRU
UHDOORFDWHVWRUDJHWRUHIOHFWWKHQXPEHURIVHOHFWOLVWLWHPVVSHFLILHGE\VTOGUHVHW
VTOQDQGYHUVLRQWKHQH[HFXWHisc_dsql_describe()DJDLQ
if (out_sqlda->sqld > out_sqlda->sqln)
{
n = out_sqlda->sqld;
free(out_sqlda);
out_sqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(n));
out_sqlda->sqln = n;
out_sqlda->version = SQLDA_VERSION1;
isc_dsql_describe(status_vector, &trans, 1, out_sqlda);
}

 6HWXSDQ;64/9$5VWUXFWXUHIRUHDFKLWHPUHWXUQHG6HWWLQJXSDQLWHP
VWUXFWXUHLQYROYHVWKHIROORZLQJVWHSV
 &RHUFLQJDQLWHP·VGDWDW\SH RSWLRQDO 
 $OORFDWLQJORFDOVWRUDJHIRUWKHGDWDSRLQWHGWRE\WKHVTOGDWDILHOGRIWKH;64/9$57KLV
VWHSLVRQO\UHTXLUHGLIVSDFHIRUORFDOYDULDEOHVLVQRWDOORFDWHGXQWLOUXQWLPH7KH
IROORZLQJH[DPSOHLOOXVWUDWHVG\QDPLFDOORFDWLRQRIORFDOYDULDEOHVWRUDJHVSDFH
 3URYLGLQJD18//YDOXHLQGLFDWRUIRUWKHSDUDPHWHU
7KHIROORZLQJFRGHH[DPSOHLOOXVWUDWHVWKHVHVWHSVORRSLQJWKURXJKHDFK;64/9$5
VWUXFWXUHLQWKHRXWBVTOGD;64/'$
for (i=0, var = out_sqlda->sqlvar; i < out_sqlda->sqld; i++, var++)
{
dtype = (var->sqltype & ~1) /* drop flag bit for now */
switch(dtype)
{
case SQL_VARYING:
var->sqltype = SQL_TEXT;

84 INTERBASE 5
DSQL PROGRAMMING METHODS

var->sqldata = (char *)malloc(sizeof(char)*var->sqllen + 2);

break;
case SQL_TEXT:
var->sqldata = (char *)malloc(sizeof(char)*var->sqllen);
break;
case SQL_LONG:
var->sqldata = (char *)malloc(sizeof(long));
break;
. . .
/* process remaining types */
} /* end of switch statements */
if (sqltype & 1)
{
/* allocate variable to hold NULL status */
var->sqlind = (short *)malloc(sizeof(short));
}
} /* end of for loop */
)RUPRUHLQIRUPDWLRQDERXWGDWDW\SHFRHUFLRQDQG18//LQGLFDWRUVVHH´&RHUFLQJ
GDWDW\SHVµRQSDJH 

4 ([HFXWLQJDVWDWHPHQWVWULQJZLWKLQWKHFRQWH[WRIDFXUVRU
7RUHWULHYHVHOHFWOLVWLWHPVIURPDSUHSDUHGVWDWHPHQWVWULQJWKHVWULQJFDQEHH[HFXWHG
ZLWKLQWKHFRQWH[WRIDFXUVRU$OOFXUVRUGHFODUDWLRQVLQ,QWHU%DVHDUHIL[HGVWDWHPHQWV
LQVHUWHGLQWRWKHDSSOLFDWLRQEHIRUHLWLVFRPSLOHG'64/DSSOLFDWLRQGHYHORSHUVPXVW
DQWLFLSDWHWKHQHHGIRUFXUVRUVZKHQZULWLQJWKHDSSOLFDWLRQDQGGHFODUHWKHPDKHDGRIWLPH
$FXUVRULVRQO\QHHGHGWRSURFHVVSRVLWLRQHG83'$7(DQG'(/(7(VWDWHPHQWVPDGHDJDLQVW
WKHURZVUHWULHYHGE\isc_dsql_fetch()IRU6(/(&7VWDWHPHQWVWKDWVSHFLI\DQRSWLRQDO)25
83'$7(2)FODXVH
7KHIROORZLQJGHVFULSWLRQVDSSO\WRWKHVLWXDWLRQVZKHQDFXUVRULVQHHGHG)RUDQH[DPSOH
RIH[HFXWLQJDVWDWHPHQWDQGIHWFKLQJURZVZLWKRXWXVLQJDFXUVRUVHH´LVFBGVTOBIHWFK µRQ
SDJH 
$ORRSLQJFRQVWUXFWLVXVHGWRIHWFKDVLQJOHURZDWDWLPHIURPWKHFXUVRUDQGWRSURFHVV
HDFKVHOHFWOLVWLWHP FROXPQ LQWKDWURZEHIRUHWKHQH[WURZLVIHWFKHG
7RH[HFXWHDVWDWHPHQWVWULQJZLWKLQWKHFRQWH[WRIDFXUVRUDQGUHWULHYHURZVRIVHOHFWOLVW
LWHPVIROORZWKHVHVWHSV
 ([HFXWHWKHSUHSDUHGVWDWHPHQWZLWKisc_dsql_execute()
isc_dsql_execute(status_vector, &trans, &stmt, 1, NULL);

API GUIDE 85
 CHAPTER 6 WORKING WITH DYNAMIC SQL

 'HFODUHDQGRSHQDFXUVRUIRUWKHVWDWHPHQWVWULQJZLWK
isc_dsql_set_cursor_name())RUH[DPSOHWKHIROORZLQJVWDWHPHQWGHFODUHVD
FXUVRUG\QBFXUVRUIRUWKH64/VWDWHPHQWVWULQJVWPW
isc_dsql_set_cursor_name(status_vector, &stmt, "dyn_cursor", NULL);
2SHQLQJWKHFXUVRUFDXVHVWKHVWDWHPHQWVWULQJWREHH[HFXWHGDQGDQDFWLYHVHWRIURZV
WREHUHWULHYHG
 )HWFKRQHURZDWDWLPHDQGSURFHVVWKHVHOHFWOLVWLWHPV FROXPQV LWFRQWDLQV
ZLWKisc_dsql_fetch())RUH[DPSOHWKHIROORZLQJORRSVUHWULHYHRQHURZDWD
WLPHIURPG\QBFXUVRUDQGSURFHVVHDFKLWHPLQWKHUHWULHYHGURZZLWKDQ
DSSOLFDWLRQVSHFLILFIXQFWLRQFDOOHGprocess_column()
while ((fetch_stat =
isc_dsql_fetch(status_vector, &stmt, 1, out_sqlda))
== 0)
{
for (i = 0; i < out_sqlda->sqld; i++)
{
process_column(sqlda->sqlvar[i]);
}
}
if (fetch_stat != 100L)
{
/* isc_dsql_fetch returns 100 if no more rows remain to be
retrieved */
SQLCODE = isc_sqlcode(status_vector);
isc_print_sqlerror(SQLCODE, status_vector);
return(1);
}
7KHprocess_column()IXQFWLRQPHQWLRQHGLQWKLVH[DPSOHSURFHVVHVHDFKUHWXUQHG
VHOHFWOLVWLWHP7KHIROORZLQJVNHOHWRQFRGHLOOXVWUDWHVKRZVXFKDIXQFWLRQFDQEHVHWXS
void process_column(XSQLVAR *var)
{
/* test for NULL value */
if ((var->sqltype & 1) && (*(var->sqlind) = -1))
{
/* process the NULL value here */
}
else
{
/* process the data instead */
}
. . .

86 INTERBASE 5
DSQL PROGRAMMING METHODS

}
 :KHQDOOWKHURZVDUHIHWFKHGFORVHWKHFXUVRUZLWK
isc_dsql_free_statement()
isc_dsql_free_statement(status_vector, &stmt, DSQL_close);

4 5HH[HFXWLQJDTXHU\VWDWHPHQWVWULQJZLWKRXWSDUDPHWHUV
2QFHDTXHU\VWDWHPHQWVWULQJZLWKRXWSDUDPHWHUVLVSUHSDUHGLWFDQEHH[HFXWHGDVRIWHQDV
UHTXLUHGLQDQDSSOLFDWLRQE\FORVLQJDQGUHRSHQLQJLWVFXUVRU
7RUHRSHQDFXUVRUDQGSURFHVVVHOHFWOLVWLWHPVUHSHDWVWHSV²RI´([HFXWLQJDVWDWHPHQW
VWULQJZLWKLQWKHFRQWH[WRIDFXUVRUµRQSDJH 

Method 4: Query statements with parameters

7KHUHDUHIRXUVWHSVWRSURFHVVLQJDQ64/TXHU\VWDWHPHQWVWULQJZLWKSODFHKROGHU
SDUDPHWHUV
 3UHSDUHDQLQSXW;64/'$WRSURFHVVDVWDWHPHQWVWULQJ·VSDUDPHWHUV
 3UHSDUHDQRXWSXW;64/'$WRSURFHVVWKHVHOHFWOLVWLWHPVUHWXUQHGZKHQWKH
TXHU\LVH[HFXWHG
 3UHSDUHWKHVWDWHPHQWVWULQJDQGLWVSDUDPHWHUV
 8VHDFXUVRUWRH[HFXWHWKHVWDWHPHQWXVLQJLQSXWSDUDPHWHUYDOXHVIURPDQ
LQSXW;64/'$DQGWRUHWULHYHVHOHFWOLVWLWHPVIURPWKHRXWSXW;64/'$

4 3UHSDULQJWKHLQSXW;64/'$
3ODFHKROGHUSDUDPHWHUVDUHUHSODFHGZLWKDFWXDOGDWDEHIRUHDSUHSDUHG64/VWDWHPHQWVWULQJ
LVH[HFXWHG%HFDXVHWKRVHSDUDPHWHUVDUHXQNQRZQZKHQWKHVWDWHPHQWVWULQJLVFUHDWHGDQ
LQSXW;64/'$PXVWEHFUHDWHGWRVXSSO\SDUDPHWHUYDOXHVDWUXQWLPH7RSUHSDUHWKH
;64/'$IROORZWKHVHVWHSV
 'HFODUHDYDULDEOHWRKROGWKH;64/'$QHHGHGWRSURFHVVSDUDPHWHUV)RU
H[DPSOHWKHIROORZLQJGHFODUDWLRQFUHDWHVDQ;64/'$FDOOHGLQBVTOGD
XSQLDA *in_sqlda;

 2SWLRQDOO\GHFODUHDYDULDEOHIRUDFFHVVLQJWKH;64/9$5VWUXFWXUHRIWKH
;64/'$
XSQLVAR *var;

'HFODULQJDSRLQWHUWRWKH;64/9$5VWUXFWXUHLVQRWQHFHVVDU\EXWFDQVLPSOLI\
UHIHUHQFLQJWKHVWUXFWXUHLQVXEVHTXHQWVWDWHPHQWV

API GUIDE 87
 CHAPTER 6 WORKING WITH DYNAMIC SQL

 $OORFDWHPHPRU\IRUWKH;64/'$XVLQJWKH;64/'$B/(1*7+PDFUR7KH
IROORZLQJVWDWHPHQWDOORFDWHVVWRUDJHIRULQBVOTGD
in_sqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(10));

,QWKLVVWDWHPHQWVSDFHIRU;64/9$5VWUXFWXUHVLVDOORFDWHGDOORZLQJWKH;64/'$WR
DFFRPPRGDWHXSWRLQSXWSDUDPHWHUV2QFHVWUXFWXUHVDUHDOORFDWHGDVVLJQYDOXHVWR
WKHVTOGDWDILHOGV
 6HWWKHYHUVLRQILHOGRIWKH;64/'$WR64/'$B9(56,21DQGVHWWKHVTOQILHOG
RIWKH;64/'$WRLQGLFDWHWKHQXPEHURI;64/9$5VWUXFWXUHVDOORFDWHG
in_sqlda->version = SQLDA_VERSION1;
in_sqlda->sqln = 10;

4 3UHSDULQJWKHRXWSXW;64/'$
0RVWTXHULHVUHWXUQRQHRUPRUHURZVRIGDWDUHIHUUHGWRDVDVHOHFWOLVW%HFDXVHWKHQXPEHU
DQGNLQGRILWHPVUHWXUQHGDUHXQNQRZQZKHQDVWDWHPHQWVWULQJLVH[HFXWHGDQRXWSXW
;64/'$PXVWEHFUHDWHGWRVWRUHVHOHFWOLVWLWHPVWKDWDUHUHWXUQHGDWUXQWLPH7RSUHSDUH
WKH;64/'$IROORZWKHVHVWHSV
 'HFODUHDYDULDEOHWRKROGWKH;64/'$QHHGHGWRSURFHVVSDUDPHWHUV)RU
H[DPSOHWKHIROORZLQJGHFODUDWLRQFUHDWHVDQ;64/'$FDOOHGRXWBVTOGD
XSQLDA *out_sqlda;

 2SWLRQDOO\GHFODUHDYDULDEOHIRUDFFHVVLQJWKH;64/9$5VWUXFWXUHRIWKH
;64/'$
XSQLVAR *var;

'HFODULQJDSRLQWHUWRWKH;64/9$5VWUXFWXUHLVQRWQHFHVVDU\EXWFDQVLPSOLI\
UHIHUHQFLQJWKHVWUXFWXUHLQVXEVHTXHQWVWDWHPHQWV
 $OORFDWHPHPRU\IRUWKH;64/'$XVLQJWKH;64/'$B/(1*7+PDFUR7KH
IROORZLQJVWDWHPHQWDOORFDWHVVWRUDJHIRURXWBVTOGD
out_sqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(10));

6SDFHIRU;64/9$5VWUXFWXUHVLVDOORFDWHGLQWKLVVWDWHPHQWHQDEOLQJWKH;64/'$WR
DFFRPPRGDWHXSWRVHOHFWOLVWLWHPV
 6HWWKHYHUVLRQILHOGRIWKH;64/'$WR64/'$B9(56,21DQGVHWWKHVTOQILHOG
RIWKH;64/'$WRLQGLFDWHWKHQXPEHURI;64/9$5VWUXFWXUHVDOORFDWHG
out_sqlda->version = SQLDA_VERSION1;
out_sqlda->sqln = 10;

88 INTERBASE 5
DSQL PROGRAMMING METHODS

4 3UHSDULQJDTXHU\VWDWHPHQWVWULQJZLWK SDUDPHWHUV
$IWHUDQLQSXWDQGDQRXWSXW;64/'$DUHFUHDWHGIRUKROGLQJDVWDWHPHQWVWULQJ·VSDUDPHWHUV
DQGWKHVHOHFWOLVWLWHPVUHWXUQHGZKHQWKHVWDWHPHQWLVH[HFXWHGWKHVWDWHPHQWVWULQJFDQEH
FUHDWHGDQGSUHSDUHG:KHQDVWDWHPHQWVWULQJLVSUHSDUHG,QWHU%DVHUHSODFHVWKH
SODFHKROGHUSDUDPHWHUVLQWKHVWULQJZLWKLQIRUPDWLRQDERXWWKHDFWXDOSDUDPHWHUVXVHG7KH
LQIRUPDWLRQDERXWWKHSDUDPHWHUVPXVWEHDVVLJQHGWRWKHLQSXW;64/'$ DQGSHUKDSV
DGMXVWHG EHIRUHWKHVWDWHPHQWFDQEHH[HFXWHG:KHQWKHVWDWHPHQWVWULQJLVH[HFXWHG
,QWHU%DVHVWRUHVVHOHFWOLVWLWHPVLQWKHRXWSXW;64/'$
7RSUHSDUHDTXHU\VWDWHPHQWVWULQJZLWKSDUDPHWHUVIROORZWKHVHVWHSV
 (OLFLWDVWDWHPHQWVWULQJIURPWKHXVHURUFUHDWHRQHWKDWFRQWDLQVWKH64/
VWDWHPHQWWREHSURFHVVHG)RUH[DPSOHWKHIROORZLQJVWDWHPHQWFUHDWHVDQ64/
VWDWHPHQWVWULQJZLWKSODFHKROGHUSDUDPHWHUV
char *str = "SELECT * FROM DEPARTMENT WHERE BUDGET = ?, LOCATION = ?";

7KLVVWDWHPHQWVWULQJFRQWDLQVWZRSDUDPHWHUVDYDOXHWREHDVVLJQHGWRWKH%8'*(7
FROXPQDQGDYDOXHWREHDVVLJQHGWRWKH/2&$7,21FROXPQ
 'HFODUHDQGLQLWLDOL]HDQ64/VWDWHPHQWKDQGOHWKHQDOORFDWHLWZLWK
isc_dsql_allocate()
isc_stmt_handle stmt; /* Declare a statement handle. */
stmt = NULL; /* Set handle to NULL before allocation. */
. . .
isc_dsql_allocate_statement(status_vector, &db1, &stmt);

 3UHSDUHWKHVWDWHPHQWVWULQJZLWKisc_dsql_prepare()7KLVVHWVWKHVWDWHPHQW
KDQGOH VWPW WRUHIHUWRWKHSDUVHGIRUPDW7KHVWDWHPHQWKDQGOHLVXVHGLQ
VXEVHTXHQWFDOOVWRisc_dsql_describe()isc_dsql_describe_bind()DQG
isc_dsql_execute2()
isc_dsql_prepare(status_vector, &trans, &stmt, 0, str, 1, out_xsqlda);

 8VHisc_dsql_describe_bind()WRILOOWKHLQSXW;64/'$ZLWKLQIRUPDWLRQ
DERXWWKHSDUDPHWHUVFRQWDLQHGLQWKH64/VWDWHPHQW
isc_dsql_decribe_bind(status_vector, &stmt, 1, in_xsqlda);

 &RPSDUHWKHVTOQILHOGRIWKH;64/'$WRWKHVTOGILHOGWRGHWHUPLQHLIWKHLQSXW
GHVFULSWRUFDQDFFRPPRGDWHWKHQXPEHURISDUDPHWHUVFRQWDLQHGLQWKH
VWDWHPHQW,IQRWIUHHWKHVWRUDJHSUHYLRXVO\DOORFDWHGWRWKHLQSXWGHVFULSWRU
UHDOORFDWHVWRUDJHWRUHIOHFWWKHQXPEHURISDUDPHWHUVVSHFLILHGE\VTOGUHVHWVTOQ
DQGYHUVLRQWKHQH[HFXWHisc_dsql_describe_bind()DJDLQ
if (in_sqlda->sqld > in_sqlda->sqln)
{

API GUIDE 89
 CHAPTER 6 WORKING WITH DYNAMIC SQL

n = in_sqlda->sqld;
free(in_sqlda);
in_sqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(n));
in_sqlda->sqln = n;
in_sqlda->version = SQLDA_VERSION1;
isc_dsql_decribe_bind(status_vector, &stmt, 1, in_xsqlda);
}

 3URFHVVHDFK;64/9$5SDUDPHWHUVWUXFWXUHLQWKHLQSXW;64/'$3URFHVVLQJD
SDUDPHWHUVWUXFWXUHLQYROYHVXSWRIRXUVWHSV
 &RHUFLQJDSDUDPHWHU·VGDWDW\SH RSWLRQDO 
 $OORFDWLQJORFDOVWRUDJHIRUWKHGDWDSRLQWHGWRE\WKHVTOGDWDILHOGRIWKH;64/9$57KLV
VWHSLVRQO\UHTXLUHGLIVSDFHIRUORFDOYDULDEOHVLVQRWDOORFDWHGXQWLOUXQWLPH7KH
IROORZLQJH[DPSOHLOOXVWUDWHVG\QDPLFDOORFDWLRQRIORFDOYDULDEOHVWRUDJHVSDFH
 3URYLGLQJDYDOXHIRUWKHSDUDPHWHUFRQVLVWHQWZLWKLWVGDWDW\SH UHTXLUHG 
 3URYLGLQJD18//YDOXHLQGLFDWRUIRUWKHSDUDPHWHU
7KHVHVWHSVPXVWEHIROORZHGLQWKHRUGHUSUHVHQWHG7KHIROORZLQJFRGHH[DPSOH
LOOXVWUDWHVWKHVHVWHSVORRSLQJWKURXJKHDFK;64/9$5VWUXFWXUHLQWKHLQBVTOGD;64/'$
for (i=0, var = in_sqlda->sqlvar; i < in_sqlda->sqld; i++, var++)
{
/* Process each XSQLVAR parameter structure here.
The parameter structure is pointed to by var.*/
dtype = (var->sqltype & ~1) /* drop flag bit for now */
switch(dtype)
{
case SQL_VARYING: /* coerce to SQL_TEXT */
var->sqltype = SQL_TEXT;
/* allocate proper storage */
var->sqldata = (char *)malloc(sizeof(char)*var->sqllen);
/* Provide a value for the parameter. See case SQL_LONG. */
. . .
break;
case SQL_TEXT:
var->sqldata = (char *)malloc(sizeof(char)*var->sqllen);
/* Provide a value for the parameter. See case SQL_LONG. */
. . .
break;
case SQL_LONG:
var->sqldata = (char *)malloc(sizeof(long));
/* Provide a value for the parameter. */
*(long *)(var->sqldata) = 17;

90 INTERBASE 5
DSQL PROGRAMMING METHODS

break;
. . .
} /* end of switch statement */
if (sqltype & 1)
{
/* allocate variable to hold NULL status */
var->sqlind = (short *)malloc(sizeof(short));
}
} /* end of for loop */

)RUPRUHLQIRUPDWLRQDERXWGDWDW\SHFRHUFLRQDQG18//LQGLFDWRUVVHH´&RHUFLQJ
GDWDW\SHVµRQSDJH 
 8VHisc_dsql_describe()WRILOOWKHRXWSXW;64/'$ZLWKLQIRUPDWLRQDERXWWKH
VHOHFWOLVWLWHPVUHWXUQHGE\WKHVWDWHPHQW
isc_dsql_describe(status_vector, &trans, &stmt, out_xsqlda);

 &RPSDUHWKHVTOQILHOGRIWKH;64/'$WRWKHVTOGILHOGWRGHWHUPLQHLIWKHRXWSXW
GHVFULSWRUFDQDFFRPPRGDWHWKHQXPEHURIVHOHFWOLVWLWHPVVSHFLILHGLQWKH
VWDWHPHQW,IQRWIUHHWKHVWRUDJHSUHYLRXVO\DOORFDWHGWRWKHRXWSXWGHVFULSWRU
UHDOORFDWHVWRUDJHWRUHIOHFWWKHQXPEHURIVHOHFWOLVWLWHPVVSHFLILHGE\VTOGUHVHW
VTOQDQGYHUVLRQDQGH[HFXWH'(6&5,%(287387DJDLQ
if (out_sqlda->sqld > out_sqlda->sqln)
{
n = out_sqlda->sqld;
free(out_sqlda);
out_sqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(n));
out_sqlda->sqln = n;
out_sqlda->version = SQLDA_VERSION1;
isc_dsql_describe(status_vector, &trans, &stmt, out_xsqlda);
}

 6HWXSDQ;64/9$5VWUXFWXUHIRUHDFKLWHPUHWXUQHG6HWWLQJXSDQLWHP
VWUXFWXUHLQYROYHVWKHIROORZLQJVWHSV
 &RHUFLQJDQLWHP·VGDWDW\SH RSWLRQDO 
 $OORFDWLQJORFDOVWRUDJHIRUWKHGDWDSRLQWHGWRE\WKHVTOGDWDILHOGRIWKH;64/9$57KLV
VWHSLVRQO\UHTXLUHGLIVSDFHIRUORFDOYDULDEOHVLVQRWDOORFDWHGXQWLOUXQWLPH7KH
IROORZLQJH[DPSOHLOOXVWUDWHVG\QDPLFDOORFDWLRQRIORFDOYDULDEOHVWRUDJHVSDFH
 3URYLGLQJD18//YDOXHLQGLFDWRUIRUWKHSDUDPHWHU RSWLRQDO 
7KHIROORZLQJFRGHH[DPSOHLOOXVWUDWHVWKHVHVWHSVORRSLQJWKURXJKHDFK;64/9$5
VWUXFWXUHLQWKHRXWBVTOGD;64/'$
for (i=0, var = out_sqlda->sqlvar; i < out_sqlda->sqld; i++, var++)

API GUIDE 91
 CHAPTER 6 WORKING WITH DYNAMIC SQL

{
dtype = (var->sqltype & ~1) /* drop flag bit for now */
switch(dtype)
{
case SQL_VARYING:
var->sqltype = SQL_TEXT;
break;
case SQL_TEXT:
var->sqldata = (char *)malloc(sizeof(char)*var->sqllen);
break;
case SQL_LONG:
var->sqldata = (char *)malloc(sizeof(long));
break;
/* process remaining types */
} /* end of switch statements */
if (sqltype & 1)
{
/* allocate variable to hold NULL status */
var->sqlind = (short *)malloc(sizeof(short));
}
} /* end of for loop */

)RUPRUHLQIRUPDWLRQDERXWGDWDW\SHFRHUFLRQDQG18//LQGLFDWRUVVHH´&RHUFLQJ
GDWDW\SHVµRQSDJH 

4 ([HFXWLQJDTXHU\VWDWHPHQWVWULQJZLWKLQWKHFRQWH[WRIDFXUVRU
7RUHWULHYHVHOHFWOLVWLWHPVIURPDVWDWHPHQWVWULQJWKHVWULQJPXVWEHH[HFXWHGZLWKLQWKH
FRQWH[WRIDFXUVRU$OOFXUVRUGHFODUDWLRQVLQ,QWHU%DVHDUHIL[HGHPEHGGHGVWDWHPHQWV
LQVHUWHGLQWRWKHDSSOLFDWLRQEHIRUHLWLVFRPSLOHG'64/DSSOLFDWLRQGHYHORSHUVPXVW
DQWLFLSDWHWKHQHHGIRUFXUVRUVZKHQZULWLQJWKHDSSOLFDWLRQDQGGHFODUHWKHPDKHDGRIWLPH
$ORRSLQJFRQVWUXFWLVXVHGWRIHWFKDVLQJOHURZDWDWLPHIURPWKHFXUVRUDQGWRSURFHVV
HDFKVHOHFWOLVWLWHP FROXPQ LQWKDWURZEHIRUHWKHQH[WURZLVIHWFKHG
7RH[HFXWHDVWDWHPHQWVWULQJZLWKLQWKHFRQWH[WRIDFXUVRUDQGUHWULHYHURZVRIVHOHFWOLVW
LWHPVIROORZWKHVHVWHSV
 ([HFXWHWKHVWDWHPHQWZLWKisc_dsql_execute2()
isc_dsql_execute2(status_vector, &trans, &stmt, 1, in_xsqlda, out_xsqlda);

 'HFODUHDQGRSHQDFXUVRUIRUWKHVWDWHPHQWVWULQJZLWK
isc_dsql_set_cursor_name())RUH[DPSOHWKHIROORZLQJVWDWHPHQWGHFODUHVD
FXUVRUG\QBFXUVRUIRUWKHSUHSDUHG64/VWDWHPHQWVWULQJVWPW
isc_dsql_set_cursor_name(status_vector, &stmt, "dyn_cursor", NULL);

92 INTERBASE 5
DSQL PROGRAMMING METHODS

2SHQLQJWKHFXUVRUFDXVHVWKHVWDWHPHQWVWULQJWREHH[HFXWHGDQGDQDFWLYHVHWRIURZV
WREHUHWULHYHG
 )HWFKRQHURZDWDWLPHZLWKisc_dsql_fetch()DQGSURFHVVWKHVHOHFWOLVWLWHPV
FROXPQV LWFRQWDLQV)RUH[DPSOHWKHIROORZLQJORRSVUHWULHYHRQHURZDWD
WLPHIURPG\QBFXUVRUDQGSURFHVVHDFKLWHPLQWKHUHWULHYHGURZZLWKDQ
DSSOLFDWLRQVSHFLILFIXQFWLRQFDOOHGprocess_column()
while ((fetch_stat =
isc_dsql_fetch(status_vector, &stmt, 1, out_sqlda)) == 0)
{
for (i = 0; i < out_sqlda->sqld; i++)
{
process_column(sqlda->sqlvar[i]);
}
}
if (fetch_stat != 100L)
{
/* isc_dsql_fetch returns 100 if no more rows remain to be
retrieved */
SQLCODE = isc_sqlcode(status_vector);
isc_print_sqlerror(SQLCODE, status_vector);
return(1);
}
 :KHQDOOWKHURZVDUHIHWFKHGFORVHWKHFXUVRUZLWK
isc_dsql_free_statement()
isc_dsql_free_statement(status_vector, &stmt, DSQL_close);

4 5HH[HFXWLQJDTXHU\VWDWHPHQWVWULQJZLWK SDUDPHWHUV
2QFHDTXHU\VWDWHPHQWVWULQJZLWKSDUDPHWHUVLVSUHSDUHGLWFDQEHXVHGDVRIWHQDVUHTXLUHG
LQDQDSSOLFDWLRQ%HIRUHHDFKVXEVHTXHQWXVHWKHLQSXW;64/'$FDQEHVXSSOLHGZLWKQHZ
SDUDPHWHUDQG18//LQGLFDWRUGDWD7KHFXUVRUPXVWEHFORVHGDQGUHRSHQHGEHIRUH
SURFHVVLQJFDQRFFXU
g 7RSURYLGHQHZSDUDPHWHUVWRWKHLQSXW;64/'$IROORZVWHSVWRRI´3UHSDULQJDTXHU\
VWDWHPHQWVWULQJZLWK SDUDPHWHUVµRQSDJH 
g 7RSURYLGHQHZLQIRUPDWLRQWRWKHRXWSXW;64/'$IROORZVWHSVWRRI´3UHSDULQJDTXHU\
VWDWHPHQWVWULQJZLWK SDUDPHWHUVµRQSDJH 
g 7RUHRSHQDFXUVRUDQGSURFHVVVHOHFWOLVWLWHPVUHSHDWVWHSVWRRI´([HFXWLQJDTXHU\
VWDWHPHQWVWULQJZLWKLQWKHFRQWH[WRIDFXUVRUµRQSDJH 

API GUIDE 93
 CHAPTER 6 WORKING WITH DYNAMIC SQL

Determining an unknown statement type at runtime

$QDSSOLFDWLRQFDQXVHisc_dsql_sql_info()WRGHWHUPLQHWKHVWDWHPHQWW\SHRIDQXQNQRZQ
SUHSDUHGVWDWHPHQWIRUH[DPSOHDVWDWHPHQWHQWHUHGE\WKHXVHUDWUXQWLPH
5HTXHVWHGLQIRUPDWLRQFDQLQFOXGH
g 6WDWHPHQWW\SH
g 1XPEHURILQSXWSDUDPHWHUVUHTXLUHGE\WKHVWDWHPHQW
g 1XPEHURIRXWSXWYDOXHVUHWXUQHGE\WKHVWDWHPHQW
g 'HWDLOHGLQIRUPDWLRQUHJDUGLQJHDFKLQSXWSDUDPHWHURURXWSXWYDOXHLQFOXGLQJLWVGDWDW\SH
VFDOHDQGOHQJWK
7RXVHisc_dsql_sql_info()DOORFDWHDQLWHPOLVWEXIIHUWKDWGHVFULEHVWKHW\SHRI
LQIRUPDWLRQUHTXHVWHGDQGDOORFDWHDUHVXOWEXIIHUZKHUHWKHIXQFWLRQFDQUHWXUQWKHGHVLUHG
LQIRUPDWLRQ)RUH[DPSOHWRGHWHUPLQHWKHVWDWHPHQWW\SHRIDQXQNQRZQEXWSUHSDUHG
VWDWHPHQW\RXZRXOGDOORFDWHDRQHHOHPHQWLWHPOLVWEXIIHUDQGILOOLWZLWKWKHPDFUR
FRQVWDQWLVFBLQIRBVTOBVWPWBW\SHGHILQHGLQLEDVHK
char type_item[];
type_item[] = {isc_info_sql_stmt_type};

Note $GGLWLRQDOLQIRUPDWLRQLWHPPDFURVIRUUHTXHVWHGLWHPVFDQEHIRXQGLQLEDVHKXQGHU
WKHFRPPHQW´64/LQIRUPDWLRQLWHPVµ
7KHUHVXOWEXIIHUPXVWEHODUJHHQRXJKWRFRQWDLQDQ\GDWDUHWXUQHGE\WKHFDOO7KHSURSHU
VL]HIRUWKLVEXIIHUGHSHQGVRQWKHLQIRUPDWLRQUHTXHVWHG,IQRWHQRXJKVSDFHLVDOORFDWHG
WKHQisc_dsql_sql_info()SXWVWKHSUHGHILQHGYDOXHLVFBLQIRBWUXQFDWHGLQWKHODVWE\WHRIWKH
UHVXOWEXIIHU*HQHUDOO\ZKHQUHTXHVWLQJVWDWHPHQWW\SHLQIRUPDWLRQE\WHVLVDVXIILFLHQW
EXIIHUVL]H'HFODULQJDODUJHUWKDQQHFHVVDU\EXIIHULVDOVRVDIH$UHTXHVWWRLGHQWLI\D
VWDWHPHQWW\SHUHWXUQVWKHIROORZLQJLQIRUPDWLRQLQWKHUHVXOWEXIIHU
 2QHE\WHFRQWDLQLQJLVFBLQIRBVTOBVWPWBW\SH
 7ZRE\WHVFRQWDLQLQJDQXPEHUQWHOOLQJKRZPDQ\E\WHVFRPSRVHWKH
VXEVHTXHQWYDOXH

94 INTERBASE 5
DETERMINING AN UNKNOWN STATEMENT TYPE AT RUNTIME

 2QHRUWZRE\WHVVSHFLI\LQJWKHVWDWHPHQWW\SH7KHIROORZLQJWDEOHOLVWVWKH
VWDWHPHQWW\SHVWKDWFDQEHUHWXUQHG

Type Numeric value

isc_info_sql_stmt_select 1
isc_info_sql_stmt_insert 2
isc_info_sql_stmt_update 3
isc_info_sql_stmt_delete 4
isc_info_sql_stmt_ddl 5
isc_info_sql_stmt_get_segment 6
isc_info_sql_stmt_put_segment 7
isc_info_sql_stmt_exec_procedure 8
isc_info_sql_stmt_start_trans 9
isc_info_sql_stmt_commit 10
isc_info_sql_stmt_rollback 11
isc_info_sql_stmt_select_for_upd 12
TABLE 6.6Statement types

 $ILQDOE\WHFRQWDLQLQJWKHYDOXHLVFBLQIRBHQG  
7KHYDOXHVSODFHGLQWKHUHVXOWEXIIHUDUHQRWDOLJQHG)XUWKHUPRUHDOOQXPEHUVDUH
UHSUHVHQWHGLQDJHQHULFIRUPDWZLWKWKHOHDVWVLJQLILFDQWE\WHILUVWDQGWKHPRVWVLJQLILFDQW
E\WHODVW6LJQHGQXPEHUVKDYHWKHVLJQLQWKHODVWE\WH&RQYHUWWKHQXPEHUVWRDGDWDW\SH
QDWLYHWR\RXUV\VWHPEHIRUHLQWHUSUHWLQJWKHP
Note $OOLQIRUPDWLRQDERXWDVWDWHPHQWH[FHSWLWVW\SHFDQEHPRUHHDVLO\GHWHUPLQHGE\
FDOOLQJIXQFWLRQVRWKHUWKDQisc_dsql_sql_info())RUH[DPSOHWRGHWHUPLQHWKHLQIRUPDWLRQ
WRILOOLQDQLQSXW;64/'$FDOO isc_dsql_describe_bind()7RILOOLQDQRXWSXW;64/'$
FDOO isc_dsql_prepare()RUisc_dsql_describe()

API GUIDE 95
 CHAPTER

Working with Blob Data

Chapter7
7
7KLVFKDSWHUGHVFULEHV,QWHU%DVH·VG\QDPLFDOO\VL]DEOHGDWDW\SHFDOOHGD%OREDQGGHVFULEHV
KRZWRZRUNZLWKLWXVLQJ$3,IXQFWLRQV'HSHQGLQJRQDSDUWLFXODUDSSOLFDWLRQ\RXPLJKW
QHHGWRUHDGDOORURQO\SDUWRIWKHFKDSWHU
)RUH[DPSOHLI\RXSODQWRUHTXHVWFRQYHUVLRQRI%OREGDWDIURPRQHGDWDW\SHWRDQRWKHU
VXFKDVIURPRQHELWPDSSHGJUDSKLFIRUPDWWRDQRWKHURUIURPWKH0,',VRXQGIRUPDWWR
WKH:DYHIRUPDW\RXQHHGWRUHDGWKHHQWLUHFKDSWHU7RZULWHDFRQYHUVLRQURXWLQHFDOOHGD
ILOWHUVHH´)LOWHULQJ%OREGDWDµRQSDJH )RUIXUWKHULQIRUPDWLRQDERXWZRUNLQJZLWK%ORE
GDWDDQGILOWHUVVHHWKH3URJUDPPHU·V*XLGH
Note %OREILOWHUVDUHQRWDYDLODEOHRQ1HW:DUHVHUYHUV
,I\RXGRQRWQHHGWRUHTXHVWFRQYHUVLRQRI%OREGDWDWKHQ\RXRQO\QHHGWRUHDGWKHSDUWV
RIWKLVFKDSWHUXSWR´)LOWHULQJ%OREGDWDµRQSDJH 

97
 CHAPTER 7 WORKING WITH BLOB DATA

7KHIROORZLQJWDEOHDOSKDEHWLFDOO\OLVWVWKH$3,IXQFWLRQVIRUZRUNLQJZLWK%OREGDWD7KH
IXQFWLRQVZLOOEHGHVFULEHGDQGGHPRQVWUDWHGLQWKHUHPDLQGHURIWKLVFKDSWHU

Function Purpose
isc_blob_default_desc() Loads a Blob descriptor with default information about a Blob, including its
subtype, character set, and segment size
isc_blob_gen_bpb() Generates a Blob parameter buffer (BPB) from source and target Blob
descriptors to allow dynamic access to Blob subtype and character set
information
isc_blob_info() Returns information about an open Blob
isc_blob_lookup_desc() Determines the subtype, character set, and segment size of a Blob, given a
table name and Blob column name
isc_blob_set_desc() Initializes a Blob descriptor from parameters passed to it
isc_cancel_blob() Discards a Blob
isc_close_blob() Closes an open Blob
isc_create_blob2() Creates and opens a Blob for write access, and optionally specifies a filter
to be used to translate the Blob from one subtype to another
isc_get_segment() Retrieves data from a Blob column in a row returned by execution of a
SELECT statement
isc_open_blob2() Opens an existing Blob for retrieval, and optionally specifies a filter to be
used to translate the Blob from one subtype to another
isc_put_segment() Writes data into a Blob
TABLE 7.1 API Blob functions

What is a Blob?
$%OREODUJHREMHFWWKDWFDQQRWHDVLO\EHVWRUHGLQDGDWDEDVHDVRQHRIWKHVWDQGDUGGDWDW\SHV
<RXFDQXVHD%OREWRVWRUHODUJHDPRXQWVRIGDWDRIYDULRXVW\SHVLQFOXGLQJ
g %LWPDSSHGLPDJHV
g 6RXQGV
g 9LGHRVHJPHQWV
g 7H[W

98 INTERBASE 5
WHAT IS A BLOB?

,QWHU%DVHVXSSRUWRI%OREGDWDSURYLGHVDOOWKHDGYDQWDJHVRIDGDWDEDVHPDQDJHPHQW
V\VWHPLQFOXGLQJWUDQVDFWLRQFRQWUROPDLQWHQDQFHDQGDFFHVVXVLQJVWDQGDUG$3,IXQFWLRQ
FDOOV%OREGDWDLVVWRUHGLQWKHGDWDEDVHLWVHOI2WKHUV\VWHPVRQO\VWRUHSRLQWHUVLQWKH
GDWDEDVHWRQRQGDWDEDVHILOHV,QWHU%DVHVWRUHVWKHDFWXDO%OREGDWDLQWKHGDWDEDVHDQG
HVWDEOLVKHVDXQLTXHLGHQWLILFDWLRQKDQGOHLQWKHDSSURSULDWHWDEOHWRSRLQWWRWKHGDWDEDVH
ORFDWLRQRIWKH%ORE%\PDLQWDLQLQJWKH%OREGDWDZLWKLQWKHGDWDEDVH,QWHU%DVHJUHDWO\
LPSURYHVDFFHVVWRDQGPDQDJHPHQWRIWKHGDWD

How are Blob data stored?

%ORELVWKH,QWHU%DVHGDWDW\SHWKDWFDQUHSUHVHQWYDULRXVREMHFWVVXFKDVELWPDSSHGLPDJHV
VRXQGYLGHRDQGWH[W%HIRUH\RXVWRUHWKHVHLWHPVLQWKHGDWDEDVH\RXFUHDWHRUPDQDJH
WKHPDVSODWIRUPRUSURGXFWVSHFLILFILOHVRUGDWDVWUXFWXUHVVXFKDV
g 7,))3,&7%03:0)*(07$5*$RURWKHUELWPDSSHGRUYHFWRUJUDSKLFILOHV
g 0,',RU:$9VRXQGILOHV
g $XGLR9LGHR,QWHUOHDYHG)RUPDW $9, RU4XLFN7LPHYLGHRILOHV
g $6&,,0,)'2&:3[RURWKHUWH[WILOHV
g &$'ILOHV
<RXPXVWSURJUDPPDWLFDOO\ORDGWKHVHILOHVIURPPHPRU\LQWRWKHGDWDEDVHDV\RXGRDQ\
RWKHUGDWDLWHPVRUUHFRUGV\RXLQWHQGWRVWRUHLQ,QWHU%DVH)RUPRUHLQIRUPDWLRQDERXW
FUHDWLQJD%OREDQGVWRULQJGDWDLQWRLWVHH´:ULWLQJGDWDWRD%OREµRQSDJH 

Blob subtypes
$OWKRXJK\RXPDQDJH%OREGDWDLQZD\VVLPLODUWRRWKHUGDWDW\SHV,QWHU%DVHSURYLGHVPRUH
IOH[LEOHGDWDW\SLQJUXOHVIRU%OREGDWD%HFDXVHWKHUHDUHPDQ\QDWLYHGDWDW\SHVWKDW\RXFDQ
GHILQHDV%OREGDWD,QWHU%DVHWUHDWVWKHPJHQHULFDOO\DQGDOORZV\RXWRGHILQH\RXURZQ
GDWDW\SHNQRZQDVDVXEW\SH,QWHU%DVHDOVRSURYLGHVWZRSUHGHILQHGVXEW\SHVDQ
XQVWUXFWXUHGVXEW\SHJHQHUDOO\DSSOLHGWRELQDU\GDWDRUGDWDRIDQLQGHWHUPLQDWHW\SHDQG
DSSOLHGWRSODLQWH[W
8VHUGHILQHGVXEW\SHVPXVWDOZD\VEHUHSUHVHQWHGDVQHJDWLYHLQWHJHUVEHWZHHQ²DQG
²
$%OREFROXPQ·VVXEW\SHLVVSHFLILHGZKHQWKH%OREFROXPQLVGHILQHG
7KHDSSOLFDWLRQLVUHVSRQVLEOHIRUHQVXULQJWKDWGDWDVWRUHGLQD%OREFROXPQDJUHHVZLWKLWV
VXEW\SH,QWHU%DVHGRHVQRWFKHFNWKHW\SHRUIRUPDWRI%OREGDWD

API GUIDE 99
 CHAPTER 7 WORKING WITH BLOB DATA

Blob database storage

5DWKHUWKDQVWRULQJ%OREGDWDGLUHFWO\LQWKH%OREILHOGRIDWDEOHUHFRUG,QWHU%DVHVWRUHVD
%ORE,'WKHUH$%ORE,'LVDXQLTXHQXPHULFYDOXHWKDWUHIHUHQFHV%OREGDWD7KH%OREGDWD
LVVWRUHGHOVHZKHUHLQWKHGDWDEDVHLQDVHULHVRI%OREVHJPHQWVXQLWVRI%OREGDWDUHDGDQG
ZULWWHQLQFKXQNV%OREVHJPHQWVFDQEHRIYDU\LQJOHQJWK7KHOHQJWKRIDQLQGLYLGXDO
VHJPHQWLVVSHFLILHGZKHQLWLVZULWWHQ
6HJPHQWVDUHKDQG\ZKHQZRUNLQJZLWKGDWDWKDWLVWRRODUJHIRURQHDSSOLFDWLRQPHPRU\
EXIIHU%XWLWLVQRWQHFHVVDU\WRXVHPXOWLSOHVHJPHQWV\RXFDQSXWDOO\RXU%OREGDWDLQD
VLQJOHVHJPHQW
:KHQDQDSSOLFDWLRQFUHDWHVD%ORELWPXVWZULWHGDWDWRLWDVHJPHQWDWDWLPH:KHQDQ
DSSOLFDWLRQUHDGVD%ORELWUHDGVDVHJPHQWDWDWLPH)RUPRUHLQIRUPDWLRQDERXWZULWLQJ
VHJPHQWVVHH´:ULWLQJGDWDWRD%OREµRQSDJH )RUPRUHLQIRUPDWLRQDERXWUHDGLQJ
VHJPHQWVVHH´5HDGLQJGDWDIURPD%OREµRQSDJH 

Blob data operations

,QWHU%DVHVXSSRUWVWKHIROORZLQJRSHUDWLRQVRQ%OREGDWD
g 5HDGLQJIURPD%ORE
g :ULWLQJWRD%OREZKLFKLQYROYHVWKHIROORZLQJRSHUDWLRQV
 ,QVHUWLQJDQHZURZWKDWLQFOXGHV%OREGDWD
 5HSODFLQJWKHGDWDUHIHUHQFHGE\D%OREFROXPQRIDURZ
 8SGDWLQJWKHGDWDUHIHUHQFHGE\D%OREFROXPQRIDURZ
g 'HOHWLQJD%ORE
7KHIROORZLQJVHFWLRQVGHVFULEHKRZWRSHUIRUPWKHVHRSHUDWLRQV7KHVHH[DPSOHVGRQRW
LQFOXGHWKHXVHRIILOWHUVWRFRQYHUWGDWDIURPRQHVXEW\SHWRDQRWKHUDVLWLVUHDGRUZULWWHQ
)RULQIRUPDWLRQDERXWXVLQJILOWHUVVHH´:ULWLQJDQDSSOLFDWLRQWKDWUHTXHVWVILOWHULQJµRQ
SDJH 
'\QDPLF64/ '64/ $3,IXQFWLRQVDQGWKH;64/'$GDWDVWUXFWXUHDUHQHHGHGWRH[HFXWH
6(/(&7,16(57DQG83'$7(VWDWHPHQWVUHTXLUHGWRVHOHFWLQVHUWRUXSGDWHUHOHYDQW%ORE
GDWD7KHIROORZLQJVHFWLRQVLQFOXGHGHVFULSWLRQVRIWKH'64/SURJUDPPLQJPHWKRGV
UHTXLUHGWRH[HFXWHWKHVDPSOHVWDWHPHQWVSURYLGHG)RUPRUHLQIRUPDWLRQDERXW'64/
SURJUDPPLQJVHH&KDSWHU´:RUNLQJZLWK'\QDPLF64/µ

100 INTERBASE 5
BLOB DATA OPERATIONS

Reading data from a Blob

7KHUHDUHVL[VWHSVUHTXLUHGIRUUHDGLQJGDWDIURPDQH[LVWLQJ%ORE
 &UHDWHD6(/(&7VWDWHPHQWTXHU\WKDWVSHFLILHVVHOHFWLRQRIWKH%OREFROXPQ
DQGDQ\RWKHUFROXPQVGHVLUHG LQWKHURZVRILQWHUHVW
 3UHSDUHDQRXWSXW;64/'$VWUXFWXUHWRKROGWKHFROXPQGDWDIRUHDFKURZWKDW
LVIHWFKHG
 3UHSDUHWKH6(/(&7VWDWHPHQWIRUH[HFXWLRQ
 ([HFXWHWKHVWDWHPHQW
 )HWFKWKHVHOHFWHGURZVRQHE\RQH
 5HDGDQGSURFHVVLQJWKH%OREGDWDIURPHDFKURZ

4 &UHDWLQJWKH6(/(&7VWDWHPHQW
(OLFLWDVWDWHPHQWVWULQJIURPWKHXVHURUFUHDWHRQHWKDWFRQVLVWVRIWKH64/TXHU\WKDWZLOO
VHOHFWURZVFRQWDLQLQJWKH%OREGDWDRILQWHUHVW)RUH[DPSOHWKHIROORZLQJFUHDWHVDQ64/
TXHU\VWDWHPHQWVWULQJWKDWVHOHFWVWKUHHFROXPQVIURPYDULRXVURZVLQWKH352-(&7WDEOH
char *str =
"SELECT PROJ_NAME, PROJ_DESC, PRODUCT FROM PROJECT WHERE \
PRODUCT IN ("software", "hardware", "other") ORDER BY PROJ_NAME";

4 3UHSDULQJWKHRXWSXW;64/'$
0RVWTXHULHVUHWXUQRQHRUPRUHURZVRIGDWDUHIHUUHGWRDVDVHOHFWOLVW$QRXWSXW;64/'$
PXVWEHFUHDWHGWRVWRUHWKHFROXPQGDWDIRUHDFKURZWKDWLVIHWFKHG)RUD%OREFROXPQWKH
FROXPQGDWDLVDQLQWHUQDO%ORELGHQWLILHU %ORE,' WKDWLVQHHGHGWRDFFHVVWKHDFWXDOGDWD
7RSUHSDUHWKH;64/'$IROORZWKHVHVWHSV
 'HFODUHDYDULDEOHWRKROGWKH;64/'$)RUH[DPSOHWKHIROORZLQJGHFODUDWLRQ
FUHDWHVDQ;64/'$FDOOHGRXWBVTOGD
XSQLDA *out_sqlda;

 $OORFDWHPHPRU\IRUWKH;64/'$XVLQJWKH;64/'$B/(1*7+PDFUR7KH
;64/'$PXVWFRQWDLQRQH;64/9$5VXEVWUXFWXUHIRUHDFKFROXPQWREH
IHWFKHG7KHIROORZLQJVWDWHPHQWDOORFDWHVVWRUDJHIRUDQRXWSXW;64/'$
RXWBVTOGD ZLWKWKUHH;64/9$5VXEVWUXFWXUHV
out_sqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(3));

 6HWWKHYHUVLRQILHOGRIWKH;64/'$WR64/'$B9(56,21DQGVHWWKHVTOQILHOG
RIWKH;64/'$WRLQGLFDWHWKHQXPEHURI;64/9$5VXEVWUXFWXUHVDOORFDWHG

API GUIDE 101

 CHAPTER 7 WORKING WITH BLOB DATA

out_sqlda->version = SQLDA_VERSION1;
out_sqlda->sqln = 3;

4 3UHSDULQJWKH6(/(&7VWDWHPHQWIRUH[HFXWLRQ
$IWHUDQ;64/'$LVFUHDWHGIRUKROGLQJWKHFROXPQGDWDIRUHDFKVHOHFWHGURZWKHTXHU\
VWDWHPHQWVWULQJFDQEHSUHSDUHGIRUH[HFXWLRQ)ROORZWKHVHVWHSV
 'HFODUHDQGLQLWLDOL]HDQ64/VWDWHPHQWKDQGOHWKHQDOORFDWHLWZLWK
isc_dsql_allocate_statement()
isc_stmt_handle stmt; /* Declare a statement handle. */
stmt = NULL; /* Set handle to NULL before allocation. */
isc_dsql_allocate_statement(status_vector, &db_handle, &stmt);

 5HDG\WKHVWDWHPHQWVWULQJIRUH[HFXWLRQZLWKisc_dsql_prepare()7KLVFKHFNV
WKHVWULQJ VWU IRUV\QWD[HUURUVSDUVHVLWLQWRDIRUPDWWKDWFDQEHHIILFLHQWO\
H[HFXWHGDQGVHWVWKHVWDWHPHQWKDQGOH VWPW WRUHIHUWRWKLVSDUVHGIRUPDW7KH
VWDWHPHQWKDQGOHLVXVHGLQDODWHUFDOOWRisc_dsql_execute()
,I isc_dsql_prepare()LVSDVVHGDSRLQWHUWRWKHRXWSXW;64/'$DVLQWKHIROORZLQJ
H[DPSOHLWZLOOILOOLQPRVWILHOGVRIWKH;64/'$DQGDOOLWV;64/9$5VXEVWUXFWXUHVZLWK
LQIRUPDWLRQVXFKDVWKHGDWDW\SHOHQJWKDQGQDPHRIWKHFRUUHVSRQGLQJFROXPQVLQWKH
VWDWHPHQW
$VDPSOHFDOOWRisc_dsql_prepare()LV
isc_dsql_prepare(
status_vector,
&trans, /* Set by previous isc_start_transaction() call. */
&stmt, /* Statement handle set by this function call. */
0, /* Specifies statement string is null-terminated. */
str, /* Statement string. */
SQLDA_VERSION1,/* XSQLDA version number. */
out_sqlda /* XSQLDA for storing column data. */
);
 6HWXSDQ;64/9$5VWUXFWXUHIRUHDFKFROXPQ6HWWLQJXSDQ;64/9$5VWUXFWXUH
LQYROYHVWKHIROORZLQJVWHSV
)RUFROXPQVZKRVHW\SHVDUHNQRZQDWFRPSLOHWLPH
 6SHFLI\WKHFROXPQ·VGDWDW\SH LILWZDVQRWVHWE\isc_dsql_prepare()DVSUHYLRXVO\
GHVFULEHG 
 3RLQWWKHVTOGDWDILHOGRIWKH;64/9$5WRDQDSSURSULDWHORFDOYDULDEOH
)RUFROXPQVZKRVHW\SHVDUHQRWNQRZQXQWLOUXQWLPH
 &RHUFHWKHLWHP·VGDWDW\SH RSWLRQDO IRUH[DPSOHIURP64/B9$5<,1*WR64/B7(;7

102 INTERBASE 5
BLOB DATA OPERATIONS

 '\QDPLFDOO\DOORFDWHORFDOVWRUDJHIRUWKHGDWDSRLQWHGWRE\WKHVTOGDWDILHOGRIWKH
;64/9$5
)RUERWK
 6SHFLI\WKHQXPEHURIE\WHVRIGDWDWREHUHWULHYHGLQWRVTOGDWD
 3URYLGHD18//YDOXHLQGLFDWRUIRUWKHSDUDPHWHU
'DWDUHWULHYDOIRU%ORE DQGDUUD\ FROXPQVLVGLIIHUHQWIURPRWKHUW\SHVRIFROXPQVVR
WKH;64/9$5ILHOGVPXVWEHVHWGLIIHUHQWO\)RUQRQ%ORE DQGQRQDUUD\ FROXPQV
isc_dsql_prepare()VHWVHDFK;64/9$5VTOW\SHILHOGWRWKHDSSURSULDWHILHOGW\SHDQGWKH
GDWDUHWULHYHGZKHQDVHOHFWOLVWURZ·VGDWDLVIHWFKHGLVSODFHGLQWRWKHVTOGDWDVSDFH
DOORFDWHGIRUWKHFROXPQ)RU%OREFROXPQVWKHW\SHPXVWEHVHWWR64/B%ORE RU
64/B%ORELID18//LQGLFDWRULVGHVLUHG ,QWHU%DVHVWRUHVWKHLQWHUQDO%ORELGHQWLILHU
%ORE,' QRWWKH%OREGDWDLQWKHVTOGDWDVSDFHZKHQDURZ·VGDWDLVIHWFKHGVR\RXPXVW
SRLQWVTOGDWDWRDQDUHDWKHVL]HRID%ORE,'7RVHHKRZWRUHWULHYHWKHDFWXDO%OREGDWD
RQFH\RXKDYHD%ORE,'VHH´5HDGLQJGDWDIURPD%OREµRQSDJH 
7KHIROORZLQJFRGHH[DPSOHLOOXVWUDWHVWKHDVVLJQPHQWVIRU%OREDQGQRQ%OREFROXPQV
ZKRVHW\SHVDUHNQRZQDWFRPSLOHWLPH)RUH[DPSOHVRIKDQGOLQJGDWDW\SHVWKDWDUH
XQNQRZQXQWLOUXQWLPHVHH&KDSWHU´:RUNLQJZLWK'\QDPLF64/µ
#define PROJLEN 20
#define TYPELEN 12
ISC_QUAD blob_id;
char proj_name[PROJLEN + 1];
char prod_type[TYPELEN + 1];
short flag0, flag1, flag2;
out_sqlda->sqlvar[0].sqldata = proj_name;
out_sqlda->sqlvar[0].sqltype = SQL_TEXT + 1;
out_sqlda->sqlvar[0].sqllen = PROJLEN;
out_sqlda->sqlvar[0].sqlind = &flag0;
out_sqlda->sqlvar[1].sqldata = (char *) &blob_id;
out_sqlda->sqlvar[1].sqltype = SQL_Blob + 1;
out_sqlda->sqlvar[1].sqllen = sizeof(ISC_QUAD);
out_sqlda->sqlvar[1].sqlind = &flag1;
out_sqlda->sqlvar[2].sqldata = prod_type;
out_sqlda->sqlvar[2].sqltype = SQL_TEXT + 1;
out_sqlda->sqlvar[2].sqllen = TYPELEN;
out_sqlda->sqlvar[2].sqlind = &flag2;

4 ([HFXWLQJWKHVWDWHPHQW
2QFHWKHTXHU\VWDWHPHQWVWULQJLVSUHSDUHGLWFDQEHH[HFXWHG
isc_dsql_execute(

API GUIDE 103

 CHAPTER 7 WORKING WITH BLOB DATA

status_vector,
&trans, /* set by previous isc_start_transaction() call */
&stmt, /* allocated above by isc_dsql_allocate_statement() */
1, /* XSQLDA version number */
NULL /* NULL since stmt doesn’t have input values */
);
7KLVVWDWHPHQWFUHDWHVDVHOHFWOLVWWKHURZVUHWXUQHGE\H[HFXWLRQRIWKHVWDWHPHQW

4 )HWFKLQJVHOHFWHGURZV
$ORRSLQJFRQVWUXFWLVXVHGWRIHWFK LQWRWKHRXWSXW;64/'$ WKHFROXPQGDWDIRUDVLQJOH
URZDWDWLPHIURPWKHVHOHFWOLVWDQGWRSURFHVVHDFKURZEHIRUHWKHQH[WURZLVIHWFKHG(DFK
H[HFXWLRQRIisc_dsql_fetch()IHWFKHVWKHFROXPQGDWDLQWRWKHFRUUHVSRQGLQJ;64/9$5
VXEVWUXFWXUHVRIRXWBVTOGD)RUWKH%OREFROXPQWKH%ORE,'QRWWKHDFWXDO%OREGDWDLV
IHWFKHG
ISC_STATUS fetch_stat;
long SQLCODE;
. . .
while ((fetch_stat =
isc_dsql_fetch(status_vector, &stmt, 1, out_sqlda))
== 0)
{
proj_name[PROJLEN] = ’\0’;
prod_type[TYPELEN] = ’\0’;
printf("\nPROJECT: %–20s TYPE: %–15s\n\n",
proj_name, prod_type);
/* Read and process the Blob data (see next section) */
}
if (fetch_stat != 100L)
{
/* isc_dsql_fetch returns 100 if no more rows remain to be
retrieved */
SQLCODE = isc_sqlcode(status_vector);
isc_print_sqlerror(SQLCODE, status_vector);
return(1);
}

4 5HDGLQJDQGSURFHVVLQJWKH%OREGDWD
7RUHDGDQGSURFHVVWKH%OREGDWD
 'HFODUHDQGLQLWLDOL]HD%OREKDQGOH
isc_blob_handle blob_handle; /* Declare a Blob handle. */
blob_handle = NULL; /* Set handle to NULL before using it */

104 INTERBASE 5
BLOB DATA OPERATIONS

 &UHDWHDEXIIHUIRUKROGLQJHDFK%OREVHJPHQWDVLWLVUHDG,WVVL]HVKRXOGEHWKH
PD[LPXPVL]HVHJPHQW\RXUSURJUDPH[SHFWVWREHUHDGIURPWKH%ORE
char blob_segment[80];

 'HFODUHDQXQVLJQHGVKRUWYDULDEOHLQWRZKLFK,QWHU%DVHZLOOVWRUHWKHDFWXDO
OHQJWKRIHDFKVHJPHQWUHDG
unsigned short actual_seg_len;

 2SHQWKH%OREZLWKWKHIHWFKHGEOREBLG
isc_open_blob2(
status_vector,
&db_handle,
&trans,
&blob_handle,/* set by this function to refer to the Blob */
&blob_id, /* Blob ID put into out_sqlda by isc_dsql_fetch() */
0, /* BPB length = 0; no filter will be used */
NULL /* NULL BPB, since no filter will be used */
);
 5HDGDOOWKH%OREGDWDE\FDOOLQJisc_get_segment()UHSHDWHGO\WRJHWHDFK%ORE
VHJPHQWDQGLWVOHQJWK3URFHVVHDFKVHJPHQWUHDG,QWKHIROORZLQJH[DPSOH
´SURFHVVLQJµFRQVLVWVRISULQWLQJHDFK%OREDVLWLVUHDG
blob_stat = isc_get_segment(
status_vector,
&blob_handle, /* set by isc_open_blob2()*/
&actual_seg_len, /* length of segment read */
sizeof(blob_segment), /* length of segment buffer */
blob_segment /* segment buffer */
);
while (blob_stat == 0 || status_vector[1] == isc_segment)
{
/* isc_get_segment returns 0 if a segment was successfully read. */
/* status_vector[1] is set to isc_segment if only part of a */
/* segment was read due to the buffer (blob_segment) not being */
/* large enough. In that case, the following calls to */
/* isc_get_segment() read the rest of the buffer. */
printf("%*.*s", actual_seg_len, actual_seg_len, blob_segment);
blob_stat = isc_get_segment(status_vector, &blob_handle,
&actual_seg_len, sizeof(blob_segment), blob_segment);
printf("\n");
};
printf("\n");

 &ORVHWKH%ORE

API GUIDE 105

 CHAPTER 7 WORKING WITH BLOB DATA

isc_close_blob(status_vector, &blob_handle);

Writing data to a Blob

%HIRUH\RXFDQFUHDWHDQHZ%OREDQGZULWHGDWDWRLW\RXPXVWGRDWOHDVWRQHRIWKH
IROORZLQJ
g ,QFOXGH%OREGDWDLQDURZWREHLQVHUWHGLQWRDWDEOH
g 5HSODFHWKHGDWDUHIHUHQFHGE\D%OREFROXPQRIDURZ
g 8SGDWHWKHGDWDUHIHUHQFHGE\D%OREFROXPQRIDURZ
7KHHQWU\LQD%OREFROXPQRIDURZGRHVQRWDFWXDOO\FRQWDLQ%OREGDWD5DWKHULWKDVD%ORE
,'UHIHUULQJWRWKHGDWDZKLFKLVVWRUHGHOVHZKHUH6RWRVHWRUPRGLI\D%OREFROXPQ\RX
QHHGWRVHW RUUHVHW WKH%ORE,'VWRUHGLQLW,ID%OREFROXPQFRQWDLQVD%ORE,'DQG\RX
PRGLI\WKHFROXPQWRUHIHUWRDGLIIHUHQW%ORE RUWRFRQWDLQ18// WKH%OREUHIHUHQFHGE\
WKHSUHYLRXVO\VWRUHG%ORE,'ZLOOEHGHOHWHGGXULQJWKHQH[WJDUEDJHFROOHFWLRQ
$OOWKHVHRSHUDWLRQVUHTXLUHWKHIROORZLQJVWHSV
 3UHSDUHDQDSSURSULDWH'64/VWDWHPHQW7KLVZLOOEHDQ,16(57VWDWHPHQWLI
\RXDUHLQVHUWLQJDQHZURZLQWRDWDEOHRUDQ83'$7(VWDWHPHQWIRUPRGLI\LQJ
DURZ(DFKRIWKHVHVWDWHPHQWVZLOOQHHGDFRUUHVSRQGLQJLQSXW;64/'$
VWUXFWXUHIRUVXSSO\LQJSDUDPHWHUYDOXHVWRWKHVWDWHPHQWDWUXQWLPH7KH%ORE
,'RIDQHZ%OREZLOOEHRQHRIWKHYDOXHVSDVVHG
 &UHDWHDQHZ%OREDQGZULWHGDWDLQWRLW
 $VVRFLDWHWKH%ORE,'RIWKHQHZ%OREZLWKWKH%OREFROXPQRIWKHWDEOHURZ
E\H[HFXWLQJWKH83'$7(RU,16(57VWDWHPHQW
1RWHWKDW\RXFDQQRWXSGDWH%OREGDWDGLUHFWO\,I\RXZDQWWRPRGLI\%OREGDWD\RXPXVW
g &UHDWHDQHZ%ORE
g 5HDGWKHROG%OREGDWDLQWRDEXIIHUZKHUH\RXFDQHGLWRUPRGLI\LW
g :ULWHWKHPRGLILHGGDWDWRWKHQHZ%ORE
g 3UHSDUHDQGH[HFXWHDQ83'$7(VWDWHPHQWWKDWZLOOPRGLI\WKH%OREFROXPQWRFRQWDLQWKH
%ORE,'RIWKHQHZ%OREUHSODFLQJWKHROG%ORE·V%ORE,'
7KHVHFWLRQVEHORZGHVFULEHWKHVWHSVUHTXLUHGWRLQVHUWUHSODFHRUXSGDWH%OREGDWD

4 3UHSDULQJWKH83'$7(RU,16(57VWDWHPHQW
7RSUHSDUHDQ83'$7(RU,16(57VWDWHPHQWIRUH[HFXWLRQIROORZWKHVHVWHSV

106 INTERBASE 5
BLOB DATA OPERATIONS

 (OLFLWDQ83'$7(RU,16(57VWDWHPHQWVWULQJIURPWKHXVHURUFUHDWHRQHIRU
LQVHUWLQJDURZRUXSGDWLQJWKHURZFRQWDLQLQJWKH%OREFROXPQRILQWHUHVW)RU
H[DPSOHWKHIROORZLQJVWDWHPHQWLVIRUXSGDWLQJWKH%OREFROXPQQDPHG
352-B'(6&LQWKHURZRIWKHWDEOH352-(&7ZKRVH352-B,'ILHOGFRQWDLQVD
YDOXHVSHFLILHGDWUXQWLPH
char *upd_str =
"UPDATE PROJECT SET PROJ_DESC = ? WHERE PROJ_ID = ?";

$VDQH[DPSOHRIDQ,16(57VWDWHPHQWWKHIROORZLQJLQVHUWVDQHZURZFRQWDLQLQJYDOXHV
LQIRXUFROXPQV
char *in_str = "INSERT INTO PROJECT (PROJ_NAME, PROJ_DESC, PRODUCT,
PROJ_ID) VALUES (?, ?, ?, ?)";

7KHUHPDLQLQJVWHSVUHIHURQO\WR83'$7(VWDWHPHQWVEXWWKHDFWLRQVDSSO\WR,16(57
VWDWHPHQWVDVZHOO
 'HFODUHDYDULDEOHWRKROGWKHLQSXW;64/'$QHHGHGWRVXSSO\SDUDPHWHUYDOXHV
WRWKH83'$7(VWDWHPHQWDWUXQWLPH)RUH[DPSOHWKHIROORZLQJGHFODUDWLRQ
FUHDWHVDQ;64/'$FDOOHGLQBVTOGD
XSQLDA *in_sqlda;

 $OORFDWHPHPRU\IRUWKHLQSXW;64/'$XVLQJWKH;64/'$B/(1*7+PDFUR
7KH;64/'$PXVWFRQWDLQRQH;64/9$5VXEVWUXFWXUHIRUHDFKSDUDPHWHUWREH
SDVVHGWRWKH83'$7(VWDWHPHQW7KHIROORZLQJVWDWHPHQWDOORFDWHVVWRUDJHIRU
DQLQSXW;64/'$ LQBVTOGD ZLWKWZR;64/9$5VXEVWUXFWXUHV
in_sqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(2));

 6HWWKHYHUVLRQILHOGRIWKH;64/'$WR64/'$B9(56,21DQGVHWWKHVTOQILHOGWR
LQGLFDWHWKHQXPEHURI;64/9$5VWUXFWXUHVDOORFDWHG
in_sqlda->version = SQLDA_VERSION1;
in_sqlda->sqln = 2;

 6HWXSWKH;64/9$5VWUXFWXUHLQWKH;64/'$IRUHDFKSDUDPHWHUWREHSDVVHG
6HWWLQJXSDQ;64/9$5VWUXFWXUHLQYROYHVWKHIROORZLQJVWHSV
 6SHFLI\LQJWKHLWHP·VGDWDW\SH
 )RUSDUDPHWHUVZKRVHW\SHVDUHNQRZQDWFRPSLOHWLPH3RLQWLQJWKHVTOGDWDILHOGRIWKH
;64/9$5WRDQDSSURSULDWHORFDOYDULDEOHWKDWZLOOFRQWDLQWKHGDWDWREHSDVVHG
 )RUSDUDPHWHUVZKRVHW\SHVDUHQRWNQRZQXQWLOUXQWLPH$OORFDWLQJORFDOVWRUDJHIRU
WKHGDWDSRLQWHGWRE\WKHVTOGDWDILHOGRIWKH;64/9$5
 6SHFLI\LQJWKHQXPEHURIE\WHVRIGDWD

API GUIDE 107

 CHAPTER 7 WORKING WITH BLOB DATA

'DWDVWRUDJHIRU%ORE DQGDUUD\ FROXPQVLVGLIIHUHQWIURPRWKHUW\SHVRIFROXPQVVR

WKH;64/9$5ILHOGVPXVWEHVHWGLIIHUHQWO\)RUQRQ%ORE DQGQRQDUUD\ FROXPQVLQSXW
SDUDPHWHUGDWDFRPHVIURPWKHVSDFHSRLQWHGWRE\VTOGDWD)RU%OREFROXPQV\RXPXVW
VHWWKHW\SHWR64/B%ORE RU64/B%ORELID18//LQGLFDWRULVGHVLUHG <RXU
DSSOLFDWLRQPXVWVWRUHVSDFHIRUWKHLQWHUQDO%ORELGHQWLILHUQRWWKH%OREGDWDLQWKH
VTOGDWDVSDFH)RUPRUHLQIRUPDWLRQDERXWFUHDWLQJD%OREVWRULQJLWV,'LQWKHVTOGDWD
VSDFHDQGDVVRFLDWLQJWKH%OREZLWKDFROXPQVHH´&UHDWLQJDQHZ%OREDQGVWRULQJGDWDµ
RQSDJH 
7KHIROORZLQJFRGHH[DPSOHLOOXVWUDWHVWKHDVVLJQPHQWVIRURQHWH[WFROXPQDQGRQH%ORE
FROXPQZKHUHWKHFROXPQW\SHVDUHNQRZQDWFRPSLOHWLPH)RUH[DPSOHVRIKDQGOLQJ
GDWDW\SHVWKDWDUHXQNQRZQXQWLOUXQWLPHVHH&KDSWHU´:RUNLQJZLWK'\QDPLF64/µ
#define PROJLEN 5
char proj_id[PROJLEN + 1];
ISC_QUAD blob_id;
in_sqlda->sqlvar[0].sqldata = (char *) &blob_id;
in_sqlda->sqlvar[0].sqltype = SQL_Blob + 1;
in_sqlda->sqlvar[0].sqllen = sizeof(ISC_QUAD);
in_sqlda->sqlvar[1].sqldata = proj_id;
in_sqlda->sqlvar[1].sqltype = SQL_TEXT;
in_sqlda->sqlvar[1].sqllen = 5;
7KHSURMBLGYDULDEOHVKRXOGEHDVVLJQHGDYDOXHDWUXQWLPH XQOHVVWKHYDOXHLVNQRZQDW
FRPSLOHWLPH 7KHEOREBLGYDULDEOHVKRXOGEHVHWWRUHIHUWRWKHQHZO\FUHDWHG%OREDV
GHVFULEHGLQWKHIROORZLQJVHFWLRQV

4 &UHDWLQJDQHZ%OREDQGVWRULQJGDWD
7RFUHDWHDQHZ%OREFRQWDLQLQJWKHGDWDWREHZULWWHQ
 'HFODUHDQGLQLWLDOL]HD%OREKDQGOH
isc_blob_handle blob_handle; /* Declare a Blob handle. */
blob_handle = NULL; /* Set handle to NULL before using it */

 'HFODUHDQGLQLWLDOL]HD%ORE,'
ISC_QUAD blob_id; /* Declare a Blob ID. */
blob_id = NULL; /* Set handle to NULL before using it */

 &UHDWHDQHZ%OREE\FDOOLQJisc_create_blob2()
isc_create_blob2(
status_vector,
&db_handle,
&trans,
&blob_handle, /* set by this function to refer to the new Blob */
&blob_id, /* Blob ID set by this function */

108 INTERBASE 5
BLOB DATA OPERATIONS

0, /* Blob Parameter Buffer length = 0; no filter will be used */

NULL /* NULL Blob Parameter Buffer, since no filter will be used */
);

7KLVIXQFWLRQFUHDWHVDQHZ%ORERSHQVLWIRUZULWHDFFHVVDQGVHWVEOREBKDQGOHWRSRLQW
WRWKHQHZ%ORE
isc_create_blob2()DOVRDVVLJQVWKH%ORED%ORE,'DQGVHWVEOREBLGWRSRLQWWRWKH%ORE
,'1RWHWKDWEOREBLGLVWKHYDULDEOHSRLQWHGWRE\WKHVTOGDWDILHOGRIWKH83'$7(
VWDWHPHQWLQSXWSDUDPHWHUWKDWVSHFLILHVWKH%OREFROXPQWREHXSGDWHG7KXVZKHQWKH
83'$7(VWDWHPHQWLVH[HFXWHGWKLVQHZ%OREZLOOEHXVHGWRXSGDWHWKH%OREFROXPQ
 :ULWHDOOWKHGDWDWREHZULWWHQWRWKH%OREE\PDNLQJDVHULHVRIFDOOVWR
isc_put_segment()7KHIROORZLQJH[DPSOHUHDGVOLQHVRIGDWDDQG
FRQFDWHQDWHVHDFKWRWKH%OREUHIHUHQFHGE\EOREBKDQGOH get_line()UHDGVWKH
QH[WOLQHRIGDWDWREHZULWWHQ
char *line;
unsigned short len;
. . .
line = get_line();
while (line)
{
len = strlen(line);
isc_put_segment(
status_vector,
&blob_handle,/* set by previous isc_create_blob2() */
len, /* length of buffer containing data to write */
line /* buffer containing data to write into Blob */
);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector);
return(1);
};
line = get_line();
};

 &ORVHWKH%ORE
isc_close_blob(status_vector, &blob_handle);

4 $VVRFLDWLQJWKHQHZ%OREZLWKWKH%OREFROXPQ
([HFXWHWKH83'$7(VWDWHPHQWWRDVVRFLDWHWKHQHZ%OREZLWKWKH%OREFROXPQLQWKHURZ
VHOHFWHGE\WKHVWDWHPHQW

API GUIDE 109

 CHAPTER 7 WORKING WITH BLOB DATA

isc_dsql_execute_immediate(
status_vector,
&db_handle,
&trans,
0, /* indicates string to execute is null-terminated */
upd_str, /* UPDATE statement string to be executed */
1, /* XSQLDA version number */
in_sqlda /* XSQLDA supplying parameters to UPDATE statement */
);

Deleting a Blob
7KHUHDUHIRXUZD\VWRGHOHWHD%ORE
g 'HOHWHWKHURZFRQWDLQLQJWKH%ORE<RXFDQXVH'64/WRH[HFXWHD'(/(7(VWDWHPHQW
g 5HSODFHWKH%OREZLWKDGLIIHUHQWRQH,ID%OREFROXPQFRQWDLQVD%ORE,'DQG\RXPRGLI\
WKHFROXPQWRUHIHUWRDGLIIHUHQW%OREWKH%OREUHIHUHQFHGE\WKHSUHYLRXVO\VWRUHG%ORE,'
ZLOOEHGHOHWHGGXULQJWKHQH[WJDUEDJHFROOHFWLRQ
g 5HVHWWR18//WKHFROXPQUHIHUULQJWRWKH%OREIRUH[DPSOHE\XVLQJ'64/WRH[HFXWHD
VWDWHPHQWOLNHWKHIROORZLQJ
UPDATE PROJECT SET PROJ_DESC = NULL WHERE PROJ_ID = "VBASE"

7KH%OREUHIHUHQFHGE\WKHSUHYLRXVO\VWRUHG%ORE,'ZLOOEHGHOHWHGGXULQJWKHQH[WJDUEDJH
FROOHFWLRQ
g 'LVFDUGD%OREDIWHULWKDVEHHQFUHDWHGEXWEHIRUHLWKDVEHHQDVVRFLDWHGZLWKDSDUWLFXODU
FROXPQRIDWDEOHURZ8VHWKHisc_cancel_blob()IXQFWLRQDVLQ
isc_cancel_blob(status_vector, &blob_handle);

Requesting information about an open Blob

$IWHUDQDSSOLFDWLRQRSHQVD%ORELWFDQREWDLQLQIRUPDWLRQDERXWWKH%ORE7KH
isc_blob_info()FDOOHQDEOHVDQDSSOLFDWLRQWRTXHU\IRU%ORELQIRUPDWLRQVXFKDVWKHWRWDO
QXPEHURIVHJPHQWVLQWKH%ORERUWKHOHQJWKLQE\WHVRIWKHORQJHVWVHJPHQW

110 INTERBASE 5
REQUESTING INFORMATION ABOUT AN OPEN BLOB

,QDGGLWLRQWRDSRLQWHUWRWKHHUURUVWDWXVYHFWRUDQGD%OREKDQGOHisc_blob_info()UHTXLUHV
WZRDSSOLFDWLRQSURYLGHGEXIIHUVDQLWHPOLVWEXIIHUZKHUHWKHDSSOLFDWLRQVSHFLILHVWKH
LQIRUPDWLRQLWQHHGVDQGDUHVXOWEXIIHUZKHUH,QWHU%DVHUHWXUQVWKHUHTXHVWHGLQIRUPDWLRQ
$QDSSOLFDWLRQSRSXODWHVWKHLWHPOLVWEXIIHUZLWKLQIRUPDWLRQUHTXHVWVSULRUWRFDOOLQJ
isc_blob_info()DQGSDVVHVLWERWKDSRLQWHUWRWKHLWHPOLVWEXIIHUDQGWKHVL]HLQE\WHVRI
WKDWEXIIHU
7KHDSSOLFDWLRQPXVWDOVRFUHDWHDUHVXOWEXIIHUODUJHHQRXJKWRKROGWKHLQIRUPDWLRQ
UHWXUQHGE\,QWHU%DVH,WSDVVHVERWKDSRLQWHUWRWKHUHVXOWEXIIHUDQGWKHVL]HLQE\WHVRI
WKDWEXIIHUWRisc_blob_info(),I,QWHU%DVHDWWHPSWVWRSDVVEDFNPRUHLQIRUPDWLRQWKDQ
FDQILWLQWKHUHVXOWEXIIHULWSXWVWKHYDOXHLVFBLQIRBWUXQFDWHGGHILQHGLQLEDVHKLQWKHILQDO
E\WHRIWKHUHVXOWEXIIHU

Item-list buffer items and result buffer values

7KHLWHPOLVWEXIIHULVDFKDUDUUD\LQWRZKLFKLVSODFHGDVHTXHQFHRIE\WHYDOXHVRQHSHU
UHTXHVWHGLWHPRILQIRUPDWLRQ(DFKE\WHLVDQLWHPW\SHVSHFLI\LQJWKHNLQGRILQIRUPDWLRQ
GHVLUHG&RPSLOHWLPHFRQVWDQWVIRUDOOLWHPW\SHVDUHGHILQHGLQLEDVHK
#define isc_info_blob_num_segments 4
#define isc_info_blob_max_segment 5
#define isc_info_blob_total_length 6
#define isc_info_blob_type 7

7KHUHVXOWEXIIHUUHWXUQVDVHULHVRIFOXVWHUVRILQIRUPDWLRQRQHSHULWHPUHTXHVWHG(DFK
FOXVWHUFRQVLVWVRIWKUHHSDUWV
 $RQHE\WHLWHPW\SH(DFKLVWKHVDPHDVRQHRIWKHLWHPW\SHVLQWKHLWHPOLVW
EXIIHU
 $E\WHQXPEHUVSHFLI\LQJWKHQXPEHURIE\WHVWKDWIROORZLQWKHUHPDLQGHURI
WKHFOXVWHU
 $YDOXHVWRUHGLQDYDULDEOHQXPEHURIE\WHVZKRVHLQWHUSUHWDWLRQGHSHQGVRQ
WKHLWHPW\SH
$FDOOLQJSURJUDPLVUHVSRQVLEOHIRULQWHUSUHWLQJWKHFRQWHQWVRIWKHUHVXOWEXIIHUDQGIRU
GHFLSKHULQJHDFKFOXVWHUDVDSSURSULDWH
7KHFOXVWHUVUHWXUQHGWRWKHUHVXOWEXIIHUDUHQRWDOLJQHG)XUWKHUPRUHDOOQXPEHUVDUH
UHSUHVHQWHGLQDJHQHULFIRUPDWZLWKWKHOHDVWVLJQLILFDQWE\WHILUVWDQGWKHPRVWVLJQLILFDQW
E\WHODVW6LJQHGQXPEHUVKDYHWKHVLJQLQWKHODVWE\WH&RQYHUWWKHQXPEHUVWRDGDWDW\SH
QDWLYHWR\RXUV\VWHPLIQHFHVVDU\EHIRUHLQWHUSUHWLQJWKHP7KH$3,FDOO
isc_vax_integer()FDQEHXVHGWRSHUIRUPWKHFRQYHUVLRQ

API GUIDE 111

 CHAPTER 7 WORKING WITH BLOB DATA

7KHIROORZLQJWDEOHOLVWVLWHPVDERXWZKLFKLQIRUPDWLRQFDQEHUHTXHVWHGDQGUHWXUQHGDQG
WKHYDOXHVUHSRUWHG

Request and return item Return value

isc_info_blob_num_segments Total number of segments
isc_info_blob_max_segment Length of the longest segment
isc_info_blob_total_length Total size, in bytes, of Blob
isc_info_blob_type Type of Blob (0: segmented, or 1: stream)
TABLE 7.2 Blob request and return items

,QDGGLWLRQWRWKHLQIRUPDWLRQ,QWHU%DVHUHWXUQVLQUHVSRQVHWRDUHTXHVW,QWHU%DVHFDQDOVR
UHWXUQRQHRUPRUHRIWKHIROORZLQJVWDWXVPHVVDJHVWRWKHUHVXOWEXIIHU(DFKVWDWXVPHVVDJH
LVRQHXQVLJQHGE\WHLQOHQJWK

Item Description
isc_info_end End of the messages
isc_info_truncated Result buffer is too small to hold any more requested information
isc_info_error Requested information is unavailable. Check the status vector for an
error code and message
TABLE 7.3 Status message return items

isc_blob_info( ) call example

7KHIROORZLQJFRGHUHTXHVWVWKHQXPEHURIVHJPHQWVDQGWKHPD[LPXPVHJPHQWVL]HIRUD
%OREDIWHULWLVRSHQHGWKHQH[DPLQHVWKHUHVXOWEXIIHU
char blob_items[] = {
isc_info_blob_max_segment, isc_info_blob_num_segments};
char res_buffer[20], *p, item;
short length;
SLONG max_size = 0L, num_segments = 0L;
ISC_STATUS status_vector[20];
isc_open_blob2(
status_vector,
&db_handle, /* database handle, set by isc_attach_database() */
&tr_handle, /* transaction handle, set by isc_start_transaction() */

112 INTERBASE 5
REQUESTING INFORMATION ABOUT AN OPEN BLOB

&blob_handle, /* set by this function to refer to the Blob */

&blob_id, /* Blob ID of the Blob to open */
0, /* BPB length = 0; no filter will be used */
NULL /* NULL BPB, since no filter will be used */
);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector);
return(1);
}
isc_blob_info(
status_vector,
&blob_handle, /* Set in isc_open_blob2() call above. */
sizeof(blob_items),/* Length of item-list buffer. */
blob_items, /* Item-list buffer. */
sizeof(res_buffer),/* Length of result buffer. */
res_buffer /* Result buffer */
);
if (status_vector[0] == 1 && status_vector[1])
{
/* An error occurred. */
isc_print_status(status_vector);
isc_close_blob(status_vector, &blob_handle);
return(1);
};
/* Extract the values returned in the result buffer. */
for (p = res_buffer; *p != isc_info_end ;)
{
item = *p++
length = (short)isc_vax_integer(p, 2);
p += 2;
switch (item)
{
case isc_info_blob_max_segment:
max_size = isc_vax_integer(p, length);
break;
case isc_info_blob_num_segments:
num_segments = isc_vax_integer(p, length);
break;
case isc_info_truncated:
/* handle error */
break;
default:
break;

API GUIDE 113

 CHAPTER 7 WORKING WITH BLOB DATA

}
p += length;
};

Blob descriptors
$%OREGHVFULSWRULVXVHGWRSURYLGHG\QDPLFDFFHVVWR%ORELQIRUPDWLRQ)RUH[DPSOHLWFDQ
EHXVHGWRVWRUHLQIRUPDWLRQDERXW%OREGDWDIRUILOWHULQJ FRQYHUVLRQ SXUSRVHVVXFKDV
FKDUDFWHUVHWLQIRUPDWLRQIRUWH[W%OREGDWDDQGVXEW\SHLQIRUPDWLRQIRUWH[WDQGQRQWH[W
%OREGDWD7ZR%OREGHVFULSWRUVDUHQHHGHGZKHQHYHUDILOWHUZLOOEHXVHGZKHQZULWLQJWRRU
UHDGLQJIURPD%ORERQHWRGHVFULEHWKHILOWHUVRXUFHGDWDDQGWKHRWKHUWRGHVFULEHWKH
WDUJHW
$%OREGHVFULSWRULVDVWUXFWXUHGHILQHGLQWKHLEDVHKKHDGHUILOHDVIROORZV
typedef struct {
short blob_desc_subtype; /* type of Blob data */
short blob_desc_charset; /* character set */
short blob_desc_segment_size; /* segment size */
unsigned char blob_desc_field_name [32]; /* Blob column name */
unsigned char blob_desc_relation_name [32]; /* table name */
} ISC_Blob_DESC;

)RUPRUHLQIRUPDWLRQDERXWWKHFKDUDFWHUVHWVUHFRJQL]HGE\,QWHU%DVHVHHWKH/DQJXDJH
5HIHUHQFH
7KHVHJPHQWVL]HRID%ORELVWKHPD[LPXPQXPEHURIE\WHVWKDWDQDSSOLFDWLRQLVH[SHFWHG
WRZULWHWRRUUHDGIURPWKH%ORE<RXFDQXVHWKLVVL]HWRDOORFDWH\RXURZQEXIIHUV
7KHEOREBGHVFBUHODWLRQBQDPHDQGEOREBGHVFBILHOGBQDPHILHOGVFRQWDLQQXOO
WHUPLQDWHGVWULQJV

Populating a Blob descriptor

7KHUHDUHIRXUSRVVLEOHZD\VWRSRSXODWHD%OREGHVFULSWRU<RXFDQGRVRE\
g &DOOLQJisc_blob_default_desc()7KLVVWRUHVGHIDXOWYDOXHVLQWRWKHGHVFULSWRUILHOGV7KH
GHIDXOWVXEW\SHLV 7(;7 VHJPHQWVL]HLVE\WHVDQGFKDUVHWLVWKHGHIDXOWFKDUVHWIRU
\RXUSURFHVV
g &DOOLQJisc_blob_lookup_desc()7KLVDFFHVVHVWKHGDWDEDVHV\VWHPPHWDGDWDWDEOHVWRORRN
XSDQGFRS\LQIRUPDWLRQIRUWKHVSHFLILHG%OREFROXPQLQWRWKHGHVFULSWRUILHOGV

114 INTERBASE 5
FILTERING BLOB DATA

g &DOOLQJisc_blob_set_desc()7KLVLQLWLDOL]HVWKHGHVFULSWRUIURPSDUDPHWHUV\RXFDOOLWZLWK
UDWKHUWKDQDFFHVVLQJWKHGDWDEDVHPHWDGDWD
g 6HWWLQJWKHGHVFULSWRUILHOGVGLUHFWO\
7KHIROORZLQJH[DPSOHFDOOVisc_blob_lookup_desc()WRORRNXSWKHFXUUHQWVXEW\SHDQG
FKDUDFWHUVHWLQIRUPDWLRQIRUD%OREFROXPQQDPHG352-B'(6&LQDWDEOHQDPHG352-(&7
,WVWRUHVWKHLQIRUPDWLRQLQWRWKHVRXUFHGHVFULSWRUIURPBGHVF
isc_blob_lookup_desc (
status_vector,
&db_handle; /* Set by previous isc_attach_database() call. */
&tr_handle, /* Set by previous isc_start_transaction() call. */
"PROJECT", /* Table name. */
"PROJ_DESC", /* Column name. */
&from_desc, /* Blob descriptor filled in by this function call. */
&global /* Global column name, returned by this function. */
)

)RUPRUHLQIRUPDWLRQDERXWWKHXVDJHRI%OREGHVFULSWRUVLQDSSOLFDWLRQVWKDWUHTXHVWGDWD
ILOWHULQJDQGIRUIXUWKHUH[DPSOHVRISRSXODWLQJ%OREGHVFULSWRUVVHH´:ULWLQJDQDSSOLFDWLRQ
WKDWUHTXHVWVILOWHULQJµRQSDJH 

Filtering Blob data

$%OREILOWHULVDURXWLQHWKDWWUDQVODWHV%OREGDWDIURPRQHVXEW\SHWRDQRWKHU
,QWHU%DVHLQFOXGHVDVHWRIVSHFLDOLQWHUQDO%OREILOWHUVWKDWFRQYHUWIURPVXEW\SH
XQVWUXFWXUHGGDWD WRVXEW\SH 7(;7 DQGIURPVXEW\SHWRVXEW\SH
,QDGGLWLRQWRXVLQJWKHVHVWDQGDUGILOWHUV\RXFDQZULWH\RXURZQH[WHUQDOILOWHUVWRSURYLGH
VSHFLDOGDWDWUDQVODWLRQ)RUH[DPSOH\RXPLJKWGHYHORSDILOWHUWRFRQYHUWRQHLPDJHIRUPDW
WRDQRWKHUIRULQVWDQFHWRGLVSOD\WKHVDPHLPDJHRQPRQLWRUVZLWKGLIIHUHQWUHVROXWLRQV2U
\RXPLJKWFRQYHUWDELQDU\%OREWRSODLQWH[WDQGEDFNDJDLQWREHDEOHWRPRYHWKHILOHPRUH
HDVLO\IURPRQHV\VWHPWRDQRWKHU
,I\RXGHILQHILOWHUV\RXFDQDVVLJQWKHPVXEW\SHLGHQWLILHUVIURP²WR²
7KHIROORZLQJVHFWLRQVSURYLGHDQRYHUYLHZRIKRZWRZULWH%OREILOWHUVIROORZHGE\GHWDLOV
RIKRZWRZULWHDQDSSOLFDWLRQWKDWUHTXLUHVILOWHULQJ)RUPRUHLQIRUPDWLRQDERXWZULWLQJ
%OREILOWHUVVHHWKH3URJUDPPHU·V*XLGH
Note %OREILOWHUVDUHDYDLODEOHIRUGDWDEDVHVUHVLGLQJRQDOO,QWHU%DVHVHUYHUSODWIRUPVH[FHSW
1HW:DUHZKHUH%OREILOWHUVFDQQRWEHFUHDWHGRUXVHG

API GUIDE 115

 CHAPTER 7 WORKING WITH BLOB DATA

Using your own filters

8QOLNHWKHVWDQGDUG,QWHU%DVHILOWHUVWKDWFRQYHUWEHWZHHQVXEW\SHDQGVXEW\SHDQ
H[WHUQDO%OREILOWHULVJHQHUDOO\SDUWRIDOLEUDU\RIURXWLQHV\RXFUHDWHDQGOLQNWRDQ
DSSOLFDWLRQ
<RXFDQZULWH%OREILOWHUVLQ&RU3DVFDO RUDQ\ODQJXDJHWKDWFDQEHFDOOHGIURP& 7RXVH
\RXURZQILOWHUVIROORZWKHVHVWHSV
 'HFLGHZKLFKILOWHUV\RXQHHGWRZULWH
 :ULWHWKHILOWHUVLQDKRVWODQJXDJH
 %XLOGDVKDUHGILOWHUOLEUDU\
 0DNHWKHILOWHUOLEUDU\DYDLODEOH
 'HILQHWKHILOWHUVWRWKHGDWDEDVH
 :ULWHDQDSSOLFDWLRQWKDWUHTXHVWVILOWHULQJ
6WHSVQXPEHUHGDQGDUHGHVFULEHGLQJUHDWHUGHWDLOLQWKHIROORZLQJVHFWLRQV

Declaring an external Blob filter to the database

7RGHFODUHDQH[WHUQDOILOWHUWRDGDWDEDVHXVHWKH'(&/$5(),/7(5VWDWHPHQW)RUH[DPSOH
WKHIROORZLQJVWDWHPHQWGHFODUHVWKHILOWHU6$03/(
DECLARE FILTER SAMPLE
INPUT TYPE –1 OUTPUT_TYPE –2
ENTRY POINT "FilterFunction"
MODULE_NAME "filter.dll";

,QWKHH[DPSOHWKHILOWHU·VLQSXWVXEW\SHLVGHILQHGDV²DQGLWVRXWSXWVXEW\SHDV
²,IVXEW\SH²VSHFLILHVORZHUFDVHWH[WDQGVXEW\SH²XSSHUFDVHWH[WWKHQWKHSXUSRVH
RIILOWHU6$03/(ZRXOGEHWRWUDQVODWH%OREGDWDIURPORZHUFDVHWH[WWRXSSHUFDVHWH[W
7KH(175<B32,17DQG02'8/(B1$0(SDUDPHWHUVVSHFLI\WKHH[WHUQDOURXWLQHWKDW
,QWHU%DVHFDOOVZKHQWKHILOWHULVLQYRNHG7KH02'8/(B1$0(SDUDPHWHUVSHFLILHVILOWHUGOO
WKHG\QDPLFOLQNOLEUDU\FRQWDLQLQJWKHILOWHU·VH[HFXWDEOHFRGH7KH(175<B32,17
SDUDPHWHUVSHFLILHVWKHHQWU\SRLQWLQWRWKH'//$OWKRXJKWKHH[DPSOHVKRZVRQO\DVLPSOH
ILOHQDPHLWLVJRRGSUDFWLFHWRVSHFLI\DIXOO\TXDOLILHGSDWKQDPHVLQFHXVHUVRI\RXU
DSSOLFDWLRQQHHGWRORDGWKHILOH

116 INTERBASE 5
FILTERING BLOB DATA

Writing an external Blob filter

,I\RXFKRRVHWRZULWH\RXURZQILOWHUV\RXPXVWKDYHDGHWDLOHGXQGHUVWDQGLQJRIWKH
GDWDW\SHV\RXSODQWRWUDQVODWH,QWHU%DVHGRHVQRWGRVWULFWGDWDW\SHFKHFNLQJRQ%OREGDWD
LWLV\RXUUHVSRQVLELOLW\

4 'HILQLQJWKHILOWHUIXQFWLRQ
:KHQZULWLQJDILOWHU\RXPXVWLQFOXGHDQHQWU\SRLQWNQRZQDVDILOWHUIXQFWLRQLQWKH
GHFODUDWLRQVHFWLRQRIWKHSURJUDP,QWHU%DVHFDOOVWKHILOWHUIXQFWLRQZKHQDQDSSOLFDWLRQ
SHUIRUPVD%OREDFFHVVRSHUDWLRQRQD%OREVSHFLILHGWRXVHWKHILOWHU$OOFRPPXQLFDWLRQ
EHWZHHQ,QWHU%DVHDQGWKHILOWHULVWKURXJKWKHILOWHUIXQFWLRQ7KHILOWHUIXQFWLRQLWVHOIPD\
FDOORWKHUIXQFWLRQVWKDWFRPSULVHWKHILOWHUH[HFXWDEOH
<RXGHFODUHWKHQDPHRIWKHILOWHUIXQFWLRQDQGWKHQDPHRIWKHILOWHUH[HFXWDEOHZLWKWKH
(175<B32,17DQG02'8/(B1$0(SDUDPHWHUVRIWKH'(&/$5(),/7(5VWDWHPHQW
$ILOWHUIXQFWLRQPXVWKDYHWKHIROORZLQJGHFODUDWLRQFDOOLQJVHTXHQFH
filter_function_name(short action, isc_blob_ctl control);

7KHSDUDPHWHUDFWLRQLVRQHRIHLJKWSRVVLEOHDFWLRQPDFURGHILQLWLRQVDQGWKHSDUDPHWHU
FRQWUROLVDQLQVWDQFHRIWKHLVFBEOREBFWO%OREFRQWUROVWUXFWXUHGHILQHGLQWKH,QWHU%DVHKHDGHU
ILOHLEDVHK7KHVHSDUDPHWHUVDUHGLVFXVVHGODWHULQWKLVFKDSWHU
7KHIROORZLQJOLVWLQJRIDVNHOHWRQILOWHUGHFODUHVWKHILOWHUIXQFWLRQMSHJBILOWHU
#include <ibase.h>
#define SUCCESS 0
#define FAILURE 1
ISC_STATUS jpeg_filter(short action, isc_blob_ctl control)
{
ISC_STATUS status = SUCCESS;
switch (action)
{
case isc_blob_filter_open:
. . .
break;
case isc_blob_filter_get_segment:
. . .
break;
case isc_blob_filter_create:
. . .
break;
case isc_blob_filter_put_segment:
. . .

API GUIDE 117

 CHAPTER 7 WORKING WITH BLOB DATA

break;
case isc_blob_filter_close:
. . .
break;
case isc_blob_filter_alloc:
. . .
break;
case isc_blob_filter_free:
. . .
break;
case isc_blob_filter_seek:
. . .
break;
default:
. . .
break;
}
return status;
}

,QWHU%DVHSDVVHVRQHRIHLJKWSRVVLEOHDFWLRQVWRWKHILOWHUIXQFWLRQMSHJBILOWHUE\ZD\RIWKH
DFWLRQSDUDPHWHUDQGDOVRSDVVHVDQLQVWDQFHRIWKH%OREFRQWUROVWUXFWXUHLVFBEOREBFWOE\ZD\
RIWKHSDUDPHWHUFRQWURO
7KHHOOLSVHV « LQWKHSUHYLRXVOLVWLQJUHSUHVHQWFRGHWKDWSHUIRUPVVRPHRSHUDWLRQVEDVHG
RQHDFKDFWLRQRUHYHQWWKDWLVOLVWHGLQWKHFDVHVWDWHPHQW0RVWRIWKHDFWLRQVFRUUHVSRQG
WR$3,IXQFWLRQVFDOOHGE\DQDSSOLFDWLRQ)RUPRUHLQIRUPDWLRQUHJDUGLQJWKHW\SHVRIFRGH
WRZULWHIRUHDFKDFWLRQVHHWKH3URJUDPPHU·V*XLGH

4 'HILQLQJWKH%OREFRQWUROVWUXFWXUH
7KHLVFBEOREBFWO%OREFRQWUROVWUXFWXUHSURYLGHVWKHIXQGDPHQWDOPHWKRGRIGDWDH[FKDQJH
EHWZHHQ,QWHU%DVHDQGDILOWHU
7KH%OREFRQWUROVWUXFWXUHLVGHILQHGDVDW\SHGHILVFBEOREBFWOLQLEDVHKDVIROORZV
typedef struct isc_blob_ctl {
ISC_STATUS (*ctl_source)();
/* Internal InterBase Blob access routine. */
struct isc_blob_ctl *ctl_source_handle;
/* Instance of isc_blob_ctl to pass to
internal InterBase Blob access routine. */
short ctl_to_sub_type;/* Target subtype. */
short ctl_from_sub_type;/* Source subtype. */
unsigned short ctl_buffer_length; /* Length of ctl_buffer. */
unsigned short ctl_segment_length; /* Length of current segment. */

118 INTERBASE 5
FILTERING BLOB DATA

unsigned short ctl_bpb_length; /* Blob parameter buffer length. */

char *ctl_bpb; /* Pointer to Blob parameter buffer. */
unsigned char *ctl_buffer; /* Pointer to segment buffer. */
ISC_LONG ctl_max_segment; /* Length of longest Blob segment. */
ISC_LONG ctl_number_segments; /* Total number of segments. */
ISC_LONG ctl_total_length; /* Total length of Blob. */
ISC_STATUS *ctl_status;/* Pointer to status vector. */
long ctl_data[8]; /* Application-specific data. */
} *ISC_Blob_CTL;

7KHSXUSRVHRIFHUWDLQLVFBEOREBFWOILHOGVGHSHQGRQWKHDFWLRQEHLQJSHUIRUPHG
)RUH[DPSOHZKHQDQDSSOLFDWLRQFDOOVWKHisc_put_segment() $3,IXQFWLRQ,QWHU%DVH
SDVVHVDQLVFBEOREBILOWHUBSXWBVHJPHQWDFWLRQWRWKHILOWHUIXQFWLRQ7KHEXIIHUSRLQWHGWRE\WKH
FWOBEXIIHUILHOGRIWKHFRQWUROVWUXFWXUHSDVVHGWRWKHILOWHUIXQFWLRQFRQWDLQVWKHVHJPHQWGDWD
WREHZULWWHQDVVSHFLILHGE\WKHDSSOLFDWLRQLQLWVFDOOWRisc_put_segment()%HFDXVHWKH
EXIIHUFRQWDLQVLQIRUPDWLRQSDVVHGLQWRWKHILOWHUIXQFWLRQLWLVFDOOHGDQ,1ILHOG7KHILOWHU
IXQFWLRQVKRXOGLQFOXGHLQVWUXFWLRQVLQWKHFDVHVWDWHPHQWXQGHUWKHLVFBEOREBILOWHUBSXWBVHJPHQW
FDVHIRUSHUIRUPLQJWKHILOWHULQJDQGWKHQSDVVLQJWKHGDWDRQIRUZULWLQJWRWKHGDWDEDVH7KLV
FDQEHGRQHE\FDOOLQJWKH FWOBVRXUFHLQWHUQDO,QWHU%DVH%OREDFFHVVURXWLQH)RUPRUH
LQIRUPDWLRQDERXWFWOBVRXUFHVHHWKH3URJUDPPHU·V*XLGH
2QWKHRWKHUKDQGZKHQDQDSSOLFDWLRQFDOOVWKHisc_get_segment()$3,IXQFWLRQWKH
EXIIHUSRLQWHGWRE\FWOBEXIIHULQWKHFRQWUROVWUXFWXUHSDVVHGWRDILOWHUIXQFWLRQLVHPSW\,Q
WKLVVLWXDWLRQ,QWHU%DVHSDVVHVDQLVFBEOREBILOWHUBJHWBVHJPHQWDFWLRQWRWKHILOWHUIXQFWLRQ7KH
ILOWHUIXQFWLRQLVFBEOREBILOWHUBJHWBVHJPHQWDFWLRQKDQGOLQJVKRXOGLQFOXGHLQVWUXFWLRQVIRUILOOLQJ
FWOBEXIIHUZLWKVHJPHQWGDWDIURPWKHGDWDEDVHWRUHWXUQWRWKHDSSOLFDWLRQ7KLVFDQEHGRQH
E\FDOOLQJWKH FWOBVRXUFHLQWHUQDO,QWHU%DVH%OREDFFHVVURXWLQH,QWKLVFDVHEHFDXVHWKH
EXIIHULVXVHGIRUILOWHUIXQFWLRQRXWSXWLWLVFDOOHGDQ287ILHOG

API GUIDE 119

 CHAPTER 7 WORKING WITH BLOB DATA

7KHIROORZLQJWDEOHGHVFULEHVHDFKRIWKHILHOGVLQWKHLVFBEOREBFWO%OREFRQWUROVWUXFWXUHDQG
ZKHWKHUWKH\DUHXVHGIRUILOWHUIXQFWLRQLQSXW ,1 RURXWSXW 287 

Field name Description

(*ctl_source)() Pointer to the internal InterBase Blob access routine (IN)
*ctl_source_handle Pointer to an instance of isc_blob_ctl to be passed to the internal InterBase Blob
access routine (IN)
ctl_to_sub_type Target subtype: information field provided to support multi-purpose filters that can
perform more than one kind of translation; this field and the next one enable such
a filter to decide which translation to perform (IN)
ctl_from_sub_type Source subtype: information field provided to support multi-purpose filters that can
perform more than one kind of translation; this field and the previous one enable
such a filter to decide which translation to perform (IN)
ctl_buffer_length For isc_blob_filter_put_segment, field is an IN field that contains the length of the
segment data contained in ctl_buffer
For isc_blob_filter_get_segment, field is an IN field set to the size of the buffer
pointed at by ctl_buffer, which is used to store the retrieved Blob data
ctl_segment_length Length of current segment. For isc_blob_filter_put_segment, field is not used
For isc_blob_filter_get_segment, field is an OUT field set to the size of the retrieved
segment (or partial segment, in the case when the buffer length ctl_buffer_length
is less than the actual segment length)
ctl_bpb_length Length of the Blob parameter buffer
*ctl_bpb Pointer to the Blob parameter buffer
*ctl_buffer Pointer to segment buffer. For isc_blob_filter_put_segment, field is an IN field that
contains the segment data
For isc_blob_filter_get_segment, field is an OUT field the filter function fills with
segment data for return to the application
TABLE 7.4 isc_blob_ctl structure field descriptions

120 INTERBASE 5
FILTERING BLOB DATA

Field name Description

ctl_max_segment Length, in bytes, of the longest segment in the Blob. Initial value is 0. The filter
function sets this field. This field is information only.
ctl_number_segments Total number of segments in the Blob. Initial value is 0. The filter function sets this
field. This field is information only.
ctl_total_length Total length, in bytes, of the Blob. Initial value is 0. The filter function sets this field.
This field is information only.
*ctl_status Pointer to InterBase status vector. (OUT )
ctl_data [8] 8-element array of application-specific data. Use this field to store resource pointers,
such as memory pointers and file handles created by the isc_blob_filter_open
handler, for example. Then, the next time the filter function is called, the resource
pointers will be available for use.
(IN/OUT)
TABLE 7.4 isc_blob_ctl structure field descriptions (continued)

4 3URJUDPPLQJILOWHUIXQFWLRQDFWLRQV
:KHQDQDSSOLFDWLRQLQYRNHVD%ORE$3,IXQFWLRQRQD%OREWREHILOWHUHG,QWHU%DVHSDVVHV
DFRUUHVSRQGLQJDFWLRQPHVVDJHWRWKHILOWHUIXQFWLRQE\ZD\RIWKHDFWLRQSDUDPHWHU7KHUH
DUHHLJKWSRVVLEOHDFWLRQV7KHIROORZLQJDFWLRQPDFURGHILQLWLRQVDUHGHFODUHGLQWKHLEDVHK
ILOH
#define isc_blob_filter_open 0
#define isc_blob_filter_get_segment 1
#define isc_blob_filter_close 2
#define isc_blob_filter_create 3
#define isc_blob_filter_put_segment 4
#define isc_blob_filter_alloc 5
#define isc_blob_filter_free 6
#define isc_blob_filter_seek 7

API GUIDE 121

 CHAPTER 7 WORKING WITH BLOB DATA

7KHIROORZLQJWDEOHOLVWVWKHDFWLRQVDQGVSHFLILHVZKHQWKHILOWHUIXQFWLRQLVLQYRNHGZLWK
HDFKSDUWLFXODUDFWLRQ0RVWRIWKHDFWLRQVDUHWKHUHVXOWRIHYHQWVWKDWRFFXUZKHQDQ
DSSOLFDWLRQLQYRNHVD%ORE$3,IXQFWLRQ

Action When filter is invoked with corresponding action

isc_blob_filter_open Invoked when an application calls isc_open_blob2()
isc_blob_filter_get_segmen Invoked when an application calls isc_get_segment()
t
isc_blob_filter_close Invoked when an application calls isc_close_blob()
isc_blob_filter_create Invoked when an application calls isc_create_blob2()
isc_blob_filter_put_segmen Invoked when an application calls isc_put_segment()
t
isc_blob_filter_alloc Invoked when InterBase initializes filter processing; not a result of a
particular application action
isc_blob_filter_free Invoked when InterBase ends filter processing; not a result of a particular
application action
isc_blob_filter_seek Reserved for internal filter use; not used by external filters
TABLE 7.5 Action constants

7KLVFRQFOXGHVWKHRYHUYLHZRIZULWLQJ%OREILOWHUV)RUGHWDLOHGLQIRUPDWLRQDERXWILOWHUVDQG
KRZWRSURJUDPILOWHUIXQFWLRQDFWLRQVDVZHOODVDUHIHUHQFHWRDILOWHUDSSOLFDWLRQH[DPSOH
VHHWKH3URJUDPPHU·V*XLGH

Writing an application that requests filtering

7RUHTXHVWILOWHULQJRI%OREGDWDDVLWLVUHDGIURPRUZULWWHQWRD%OREIROORZWKHVHVWHSVLQ
\RXUDSSOLFDWLRQ
 &UHDWHD%ORESDUDPHWHUEXIIHU %3% VSHFLI\LQJWKHVRXUFHDQGWDUJHWVXEW\SHV
DQGRSWLRQDOO\FKDUDFWHUVHWV IRU7(;7VXEW\SHV 
 &DOOHLWKHUisc_open_blob2() RU isc_create_blob2()WRRSHQD%OREIRUUHDGRU
ZULWHDFFHVVUHVSHFWLYHO\,QWKHFDOOSDVVWKH%3%ZKRVHLQIRUPDWLRQ,QWHU%DVH
ZLOOXVHWRGHWHUPLQHZKLFKILOWHUVKRXOGEHFDOOHG

122 INTERBASE 5
FILTERING BLOB DATA

4 8QGHUVWDQGLQJWKH%ORESDUDPHWHUEXIIHU
$%ORESDUDPHWHUEXIIHU %3% LVQHHGHGZKHQHYHUDILOWHUZLOOEHXVHGZKHQZULWLQJWRRU
UHDGLQJIURPD%ORE
7KH%3%LVDFKDUDUUD\YDULDEOHVSHFLILFDOO\GHFODUHGLQDQDSSOLFDWLRQWKDWFRQWDLQVWKH
VRXUFHDQGWDUJHWVXEW\SHV:KHQGDWDLVUHDGIURPRUZULWWHQWRWKH%OREDVVRFLDWHGZLWKWKH
%3%,QWHU%DVHZLOODXWRPDWLFDOO\LQYRNHDQDSSURSULDWHILOWHUEDVHGRQWKHVRXUFHDQGWDUJHW
VXEW\SHVVSHFLILHGLQWKH%3%
,IWKHVRXUFHDQGWDUJHWVXEW\SHVDUHERWK 7(;7 DQGWKH%3%DOVRVSHFLILHVGLIIHUHQW
VRXUFHDQGWDUJHWFKDUDFWHUVHWVWKHQZKHQGDWDLVUHDGIURPRUZULWWHQWRWKH%OREDVVRFLDWHG
ZLWKWKH%3%,QWHU%DVHZLOODXWRPDWLFDOO\FRQYHUWHDFKFKDUDFWHUIURPWKHVRXUFHWRWKH
WDUJHWFKDUDFWHUVHW
$%ORESDUDPHWHUEXIIHUFDQEHJHQHUDWHGLQRQHRIWZRZD\V
 ,QGLUHFWO\WKURXJK$3,FDOOVWRFUHDWHVRXUFHDQGWDUJHWGHVFULSWRUVDQGWKHQ
JHQHUDWHWKH%3%IURPWKHLQIRUPDWLRQLQWKHGHVFULSWRUV
 'LUHFWO\E\SRSXODWLQJWKH%3%DUUD\ZLWKDSSURSULDWHYDOXHV
,I\RXJHQHUDWHD%3%YLD$3,FDOOV\RXGRQRWQHHGWRNQRZWKHIRUPDWRIWKH%3%%XWLI
\RXZLVKWRGLUHFWO\JHQHUDWHD%3%WKHQ\RXPXVWNQRZWKHIRUPDW
%RWKDSSURDFKHVDUHGHVFULEHGLQWKHIROORZLQJVHFWLRQV7KHIRUPDWRIWKH%3%LV
GRFXPHQWHGLQWKHVHFWLRQDERXWGLUHFWO\SRSXODWLQJWKH%3%

GENERATING A BLOB PARAMETER BUFFER USING API CALLS

7RJHQHUDWHD%3%LQGLUHFWO\XVH$3,FDOOVWRFUHDWHVRXUFHDQGWDUJHW%OREGHVFULSWRUVDQG
WKHQFDOOisc_blob_gen_bpb()WRJHQHUDWHWKH%3%IURPWKHLQIRUPDWLRQLQWKHGHVFULSWRUV
)ROORZWKHVHVWHSV
 'HFODUHWZR%OREGHVFULSWRUVRQHIRUWKHVRXUFHDQGWKHRWKHUIRUWKHWDUJHW
)RUH[DPSOH
#include "ibase.h"
ISC_Blob_DESC from_desc, to_desc;
 6WRUHDSSURSULDWHLQIRUPDWLRQLQWKH%OREGHVFULSWRUVE\FDOOLQJRQHRIWKH
IXQFWLRQVisc_blob_default_desc()isc_blob_lookup_desc()RU
isc_blob_set_desc()RUE\VHWWLQJWKHGHVFULSWRUILHOGVGLUHFWO\7KHIROORZLQJ
H[DPSOHORRNVXSWKHFXUUHQWVXEW\SHDQGFKDUDFWHUVHWLQIRUPDWLRQIRUD%ORE
FROXPQQDPHG*8,'(%22.LQDWDEOHQDPHG7285,60DQGVWRUHVLWLQWRWKH
VRXUFHGHVFULSWRUIURPBGHVF,WWKHQVHWVWKHWDUJHWGHVFULSWRUWRBGHVFWRWKH
GHIDXOWVXEW\SH 7(;7 DQGFKDUDFWHUVHWVRWKDWWKHVRXUFHGDWDZLOOEH
FRQYHUWHGWRSODLQWH[W
isc_blob_lookup_desc (

API GUIDE 123

 CHAPTER 7 WORKING WITH BLOB DATA

status_vector,
&db_handle; /* set in previous isc_attach_database() call */
&tr_handle, /* set in previous isc_start_transaction() call */
“TOURISM", /* table name */
"GUIDEBOOK", /* column name */
&from_desc, /* Blob descriptor filled in by this function call */
&global);
if (status_vector[0] == 1 && status_vector[1])
{
/* process error */
isc_print_status(status_vector);
return(1);
};
isc_blob_default_desc (
&to_desc, /* Blob descriptor filled in by this function call */
"", /* NULL table name; it's not needed in this case */
""); /* NULL column name; it's not needed in this case */

)RUPRUHLQIRUPDWLRQDERXW%OREGHVFULSWRUVVHH´%OREGHVFULSWRUVµRQSDJH 
 'HFODUHDFKDUDFWHUDUUD\ZKLFKZLOOEHXVHGDVWKH%3%0DNHVXUHLWLVDWOHDVW
DVODUJHDVDOOWKHLQIRUPDWLRQWKDWZLOOEHVWRUHGLQWKHEXIIHU
char bpb[20];

 'HFODUHDQXQVLJQHGVKRUWYDULDEOHLQWRZKLFK,QWHU%DVHZLOOVWRUHWKHDFWXDO
OHQJWKRIWKH%3%GDWD
unsigned short actual_bpb_length;

 &DOOisc_blob_gen_bpb()WRSRSXODWHWKH%3%EDVHGRQWKHVRXUFHDQGWDUJHW
%OREGHVFULSWRUVSDVVHGWRisc_blob_gen_bpb())RUH[DPSOH
isc_blob_gen_bpb(
status_vector,
&to_desc, /* target Blob descriptor */
&from_desc, /* source Blob descriptor */
sizeof(bpb), /* length of BPB buffer */
bpb, /* buffer into which the generated BPB will be stored */
&actual_bpb_length /* actual length of generated BPB */
);

GENERATING A BLOB PARAMETER BUFFER DIRECTLY

,WLVSRVVLEOHWRJHQHUDWHD%3%GLUHFWO\

124 INTERBASE 5
FILTERING BLOB DATA

$%3%FRQVLVWVRIWKHIROORZLQJSDUWV
 $E\WHVSHFLI\LQJWKHYHUVLRQRIWKHSDUDPHWHUEXIIHUDOZD\VWKHFRPSLOHWLPH
FRQVWDQWLVFBESEBYHUVLRQ
 $FRQWLJXRXVVHULHVRIRQHRUPRUHFOXVWHUVRIE\WHVHDFKGHVFULELQJDVLQJOH
SDUDPHWHU
(DFKFOXVWHUFRQVLVWVRIWKHIROORZLQJSDUWV
 $RQHE\WHSDUDPHWHUW\SH7KHUHDUHFRPSLOHWLPHFRQVWDQWVGHILQHGIRUDOOWKH
SDUDPHWHUW\SHV IRUH[DPSOHLVFBESEBWDUJHWBW\SH 
 $RQHE\WHQXPEHUVSHFLI\LQJWKHQXPEHURIE\WHVWKDWIROORZLQWKHUHPDLQGHU
RIWKHFOXVWHU
 $YDULDEOHQXPEHURIE\WHVZKRVHLQWHUSUHWDWLRQGHSHQGVRQWKHSDUDPHWHU
W\SH
Note $OOQXPEHUVLQWKH%ORESDUDPHWHUEXIIHUPXVWEHUHSUHVHQWHGLQDJHQHULFIRUPDW
ZLWKWKHOHDVWVLJQLILFDQWE\WHILUVWDQGWKHPRVWVLJQLILFDQWE\WHODVW6LJQHGQXPEHUVVKRXOG
KDYHWKHVLJQLQWKHODVWE\WH7KH$3,IXQFWLRQisc_vax_integer()FDQEHXVHGWRUHYHUVHWKH
E\WHRUGHURIDQXPEHU)RUPRUHLQIRUPDWLRQDERXWisc_vax_integer()VHH
´LVFBYD[BLQWHJHU µRQSDJH 
7KHIROORZLQJWDEOHOLVWVWKHSDUDPHWHUW\SHVDQGWKHLUPHDQLQJ

Parameter type Description

isc_bpb_target_type Target subtype
isc_bpb_source_type Source subtype
isc_bpb_target_interp Target character set
isc_bpb_source_interp Source character set
TABLE 7.6 Blob parameter buffer parameter types

7KH%3%PXVWFRQWDLQLVFBESEBYHUVLRQDWWKHEHJLQQLQJDQGPXVWFRQWDLQFOXVWHUVVSHFLI\LQJ
WKHVRXUFHDQGWDUJHWVXEW\SHV&KDUDFWHUVHWFOXVWHUVDUHRSWLRQDO,IWKHVRXUFHDQGWDUJHW
VXEW\SHVDUHERWK 7(;7 DQGWKH%3%DOVRVSHFLILHVGLIIHUHQWVRXUFHDQGWDUJHWFKDUDFWHU
VHWVWKHQZKHQGDWDLVUHDGIURPRUZULWWHQWRWKH%OREDVVRFLDWHGZLWKWKH%3%,QWHU%DVH
ZLOODXWRPDWLFDOO\FRQYHUWHDFKFKDUDFWHUIURPWKHVRXUFHWRWKHWDUJHWFKDUDFWHUVHW
7KHIROORZLQJLVDQH[DPSOHRIGLUHFWO\FUHDWLQJD%3%IRUDILOWHUZKRVHVRXUFHVXEW\SHLV
²DQGWDUJHWVXEW\SHLV 7(;7 
char bpb[] = {
isc_bpb_version1,

API GUIDE 125

 CHAPTER 7 WORKING WITH BLOB DATA

isc_bpb_target_type,
1, /* # bytes that follow which specify target subtype */
1, /* target subtype (TEXT) */
isc_bpb_source_type,
1, /* # bytes that follow which specify source subtype */
–4, /* source subtype*/
};

2IFRXUVHLI\RXGRQRWNQRZWKHVRXUFHDQGWDUJHWVXEW\SHVXQWLOUXQWLPH\RXFDQDVVLJQ
WKRVHYDOXHVLQWKHDSSURSULDWH%3%ORFDWLRQVDWUXQWLPH

4 5HTXHVWLQJILOWHUXVDJH
<RXUHTXHVWXVDJHRIDILOWHUZKHQRSHQLQJRUFUHDWLQJD%OREIRUUHDGRUZULWHDFFHVV,QWKH
FDOOWRisc_open_blob2() RU isc_create_blob2()SDVVWKH%3%ZKRVHLQIRUPDWLRQ
,QWHU%DVHZLOOXVHWRGHWHUPLQHZKLFKILOWHUVKRXOGEHFDOOHG
7KHIROORZLQJH[DPSOHLOOXVWUDWHVFUHDWLQJDQGRSHQLQJD%OREIRUZULWHDFFHVV)RUIXUWKHU
LQIRUPDWLRQDERXWZULWLQJGDWDWRD%OREDQGXSGDWLQJD%OREFROXPQRIDWDEOHURZWRUHIHU
WRWKHQHZ%OREVHH´:ULWLQJGDWDWRD%OREµRQSDJH 
2SHQLQJD%OREIRUUHDGDFFHVVUHTXLUHVDGGLWLRQDOVWHSVWRVHOHFWWKHDSSURSULDWH%OREWREH
RSHQHG)RUPRUHLQIRUPDWLRQVHH´5HDGLQJGDWDIURPD%OREµRQSDJH 
isc_blob_handle blob_handle; /* declare at beginning */
ISC_QUAD blob_id; /* declare at beginning */
. . .
isc_create_blob2(
status_vector,
&db_handle,
&tr_handle,
&blob_handle, /* to be filled in by this function */
&blob_id, /* to be filled in by this function */
actual_bpb_length, /* length of BPB data */
&bpb /* Blob parameter buffer */
)
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector);
return(1);
}

126 INTERBASE 5
 CHAPTER

Working with Array Data

Chapter8
8
7KLVFKDSWHUGHVFULEHVDUUD\VRIGDWDW\SHVDQGKRZWRZRUNZLWKWKHPXVLQJ$3,IXQFWLRQV
,WVKRZVKRZWRVHWXSDQDUUD\GHVFULSWRUVSHFLI\LQJWKHDUUD\RUDUUD\VXEVHWWREHUHWULHYHG
RUZULWWHQWRDQGKRZWRXVHWKHWZR$3,IXQFWLRQVWKDWFRQWURODFFHVVWRDUUD\V
7KHIROORZLQJWDEOHVXPPDUL]HVWKH$3,IXQFWLRQVIRUZRUNLQJZLWKDUUD\V)LUVWWKH
IXQFWLRQVWKDWFDQEHXVHGWRSRSXODWHDQDUUD\GHVFULSWRUDUHOLVWHGIROORZHGE\WKHIXQFWLRQV
IRUDFFHVVLQJDUUD\GDWD

Function Purpose
isc_array_lookup_desc() Looks up and stores into an array descriptor the datatype, length,
scale, and dimensions for all elements in the specified array column of
the specified table
isc_array_lookup_bounds() Performs the same actions as the function,
isc_array_lookup_desc(), but also looks up and stores the upper
and lower bounds of each dimension
isc_array_set_desc() Initializes an array descriptor from parameters passed to it
isc_array_get_slice() Retrieves data from an array
isc_array_put_slice() Writes data to an array
TABLE 8.1 API array access functions

127
 CHAPTER 8 WORKING WITH ARRAY DATA

Introduction to arrays
,QWHU%DVHVXSSRUWVDUUD\VRIPRVWGDWDW\SHV8VLQJDQDUUD\HQDEOHVPXOWLSOHGDWDLWHPVWREH
VWRUHGLQDVLQJOHFROXPQ,QWHU%DVHFDQWUHDWDQDUUD\DVDVLQJOHXQLWRUDVDVHULHVRIVHSDUDWH
XQLWVFDOOHGslices8VLQJDQDUUD\LVDSSURSULDWHZKHQ
g 7KHGDWDLWHPVQDWXUDOO\IRUPDVHWRIWKHVDPHGDWDW\SH
g 7KHHQWLUHVHWRIGDWDLWHPVLQDVLQJOHGDWDEDVHFROXPQPXVWEHUHSUHVHQWHGDQGFRQWUROOHG
DVDXQLWDVRSSRVHGWRVWRULQJHDFKLWHPLQDVHSDUDWHFROXPQ
g (DFKLWHPPXVWDOVREHLGHQWLILHGDQGDFFHVVHGLQGLYLGXDOO\
7KHGDWDLWHPVLQDQDUUD\DUHFDOOHGarray elements$QDUUD\FDQFRQWDLQHOHPHQWVRIDQ\
,QWHU%DVHGDWDW\SHH[FHSW%OREDQGFDQQRWEHDQDUUD\RIDUUD\V$OORIWKHHOHPHQWVRID
SDUWLFXODUDUUD\DUHRIWKHVDPHGDWDW\SH
,QWHU%DVHVXSSRUWVPXOWLGLPHQVLRQDODUUD\VDUUD\VZLWKWRGLPHQVLRQV
0XOWLGLPHQVLRQDODUUD\VDUHVWRUHGLQURZPDMRURUGHU
$UUD\GLPHQVLRQVKDYHDVSHFLILFUDQJHRIXSSHUDQGORZHUERXQGDULHVFDOOHGsubscripts
7KHDUUD\VXEVFULSWVDUHGHILQHGZKHQDQDUUD\FROXPQLVFUHDWHG)RULQIRUPDWLRQDERXW
FUHDWLQJDQDUUD\VHHWKH/DQJXDJH5HIHUHQFH

Array database storage

,QWHU%DVHGRHVQRWVWRUHDUUD\GDWDGLUHFWO\LQWKHDUUD\ILHOGRIDWDEOHUHFRUG,QVWHDGLW
VWRUHVDQDUUD\,'WKHUH7KHDUUD\,'LVDXQLTXHQXPHULFYDOXHWKDWUHIHUHQFHVWKHDUUD\GDWD
ZKLFKLVVWRUHGHOVHZKHUHLQWKHGDWDEDVH

Array descriptors
$Qarray descriptorGHVFULEHVDQDUUD\RUDUUD\VXEVHWWREHUHWULHYHGRUZULWWHQWRWKH
,6&B$55$<B'(6&VWUXFWXUH,6&B$55$<B'(6&LVGHILQHGLQWKH,QWHU%DVHLEDVHK
KHDGHUILOHDVIROORZV
typedef struct {
unsigned char array_desc_dtype; /* Datatype */
char array_desc_scale; /* Scale for numeric datatypes */
unsigned short array_desc_length;
/* Length in bytes of each array element */
char array_desc_field_name [32]; /* Column name */
char array_desc_relation_name [32]; /* Table name */

128 INTERBASE 5
INTRODUCTION TO ARRAYS

short array_desc_dimensions; /* Number of array dimensions */

short array_desc_flags;
/* Specifies whether array is to be accessed in row-major or
column-major order */
ISC_ARRAY_BOUND array_desc_bounds [16];
/* Lower and upper bounds for each dimension */
} ISC_ARRAY_DESC;

,6&B$55$<B%281'LVGHILQHGDV
typedef struct {
short array_bound_lower; /* lower bound */
short array_bound_upper; /* upper bound */
} ISC_ARRAY_BOUND;

$QDUUD\GHVFULSWRUFRQWDLQV,6&B$55$<B%281'VWUXFWXUHVRQHIRUHDFKSRVVLEOH
GLPHQVLRQ$QDUUD\ZLWKnGLPHQVLRQVKDVXSSHUDQGORZHUERXQGVVHWIRUWKHILUVWn
,6&B$55$<B%281'VWUXFWXUHV7KHQXPEHURIDFWXDODUUD\GLPHQVLRQVLVVSHFLILHGLQWKH
array_desc_dimensionsILHOGRIWKHDUUD\GHVFULSWRU
:KHQ\RXUHWULHYHGDWDIURPDQDUUD\\RXVXSSO\DQDUUD\GHVFULSWRUGHILQLQJWKHDUUD\VOLFH
HQWLUHDUUD\RUVXEVHWRIFRQWLJXRXVDUUD\HOHPHQWV WREHUHWULHYHG6LPLODUO\ZKHQ\RXZULWH
GDWDWRDQDUUD\\RXVXSSO\DQDUUD\GHVFULSWRUGHILQLQJWKHDUUD\VOLFHWREHZULWWHQWR

Populating an array descriptor

7KHUHDUHIRXUZD\VWRSRSXODWHDQDUUD\GHVFULSWRU
g &DOOisc_array_lookup_desc()ZKLFKORRNVXS LQWKHV\VWHPPHWDGDWDWDEOHV DQGVWRUHVLQ
DQDUUD\GHVFULSWRUWKHGDWDW\SHOHQJWKVFDOHDQGGLPHQVLRQVIRUDVSHFLILHGDUUD\FROXPQ
LQDVSHFLILHGWDEOH7KLVIXQFWLRQDOVRVWRUHVWKHWDEOHDQGFROXPQQDPHLQWKHGHVFULSWRU
DQGLQLWLDOL]HVLWVarray_desc_flagsILHOGWRLQGLFDWHWKDWWKHDUUD\LVWREHDFFHVVHGLQ
URZPDMRURUGHU)RUH[DPSOH
isc_array_lookup_desc(
status_vector,
&db_handle, /* Set by isc_attach_database() */
&tr_handle, /* Set by isc_start_transaction() */
"PROJ_DEPT_BUDGET",/* table name */
"QUART_HEAD_CNT", /* array column name */
&desc /* descriptor to be filled in */
);

API GUIDE 129

 CHAPTER 8 WORKING WITH ARRAY DATA

g &DOOisc_array_lookup_bounds()ZKLFKORRNVDQGIXQFWLRQVWKHVDPHDVDFDOOWR
isc_array_lookup_desc()H[FHSWWKDWWKHIXQFWLRQisc_array_lookup_bounds()DOVR
ORRNVXSDQGVWRUHVLQWRWKHDUUD\GHVFULSWRUWKHXSSHUDQGORZHUERXQGVRIHDFKGLPHQVLRQ
g &DOOisc_array_set_desc()ZKLFKLQLWLDOL]HVWKHGHVFULSWRUIURPSDUDPHWHUVUDWKHUWKDQE\
DFFHVVLQJWKHGDWDEDVHPHWDGDWD)RUH[DPSOH
short dtype = SQL_TEXT;
short len = 8;
short numdims = 2;
isc_array_set_desc(
status_vector,
"TABLE1", /* table name */
"CHAR_ARRAY", /* array column name */
&dtype, /* datatype of elements */
&len, /* length of each element */
&numdims, /* number of array dimensions */
&desc /* descriptor to be filled in */
);

g 6HWWLQJWKHGHVFULSWRUILHOGVGLUHFWO\$QH[DPSOHRIVHWWLQJWKHarray_desc_dimensions
ILHOGRIWKHGHVFULSWRUdesc,LV
desc.array_desc_dimensions = 2;

)RUFRPSOHWHV\QWD[DQGLQIRUPDWLRQDERXWisc_array_lookup_bounds()
isc_array_lookup_desc()DQGisc_array_set_desc()VHH&KDSWHU´$3,)XQFWLRQ
5HIHUHQFHµ

Accessing array data

,QWHU%DVHVXSSRUWVWKHIROORZLQJRSHUDWLRQVRQDUUD\GDWD
g 5HDGLQJIURPDQDUUD\RUDUUD\VOLFH
g :ULWLQJWRDQDUUD\
à ,QFOXGLQJDQHZDUUD\LQDURZWREHLQVHUWHGLQWRDWDEOH
à 5HSODFLQJWKHDUUD\UHIHUHQFHGE\DQDUUD\FROXPQRIDURZZLWKDQHZDUUD\
à 8SGDWLQJWKHDUUD\UHIHUHQFHGE\DQDUUD\FROXPQRIDURZE\PRGLI\LQJWKHDUUD\GDWDRU
DVOLFHRIWKHGDWD
g 'HOHWLQJDQDUUD\

130 INTERBASE 5
ACCESSING ARRAY DATA

'\QDPLF64/ '64/ $3,IXQFWLRQVDQGWKH;64/'$GDWDVWUXFWXUHDUHQHHGHGWRH[HFXWH

6(/(&7,16(57DQG83'$7(VWDWHPHQWVUHTXLUHGWRVHOHFWLQVHUWRUXSGDWHUHOHYDQW
DUUD\GDWD7KHIROORZLQJVHFWLRQVLQFOXGHGHVFULSWLRQVRIWKH'64/SURJUDPPLQJPHWKRGV
UHTXLUHGWRH[HFXWHWKHVDPSOHVWDWHPHQWVSURYLGHG
)RUPRUHLQIRUPDWLRQDERXW'64/DQGWKH;64/'$VHH&KDSWHU´:RUNLQJZLWK
'\QDPLF64/µ
Note 7KHIROORZLQJDUUD\RSHUDWLRQVDUHnotVXSSRUWHG
g 5HIHUHQFLQJDUUD\GLPHQVLRQVG\QDPLFDOO\LQ'64/
g 6HWWLQJLQGLYLGXDODUUD\HOHPHQWVWR18//
g 8VLQJDJJUHJDWHIXQFWLRQVVXFKDV0,1 DQG0$; ZLWKDUUD\V
g 5HIHUHQFLQJDUUD\VLQWKH*5283%<FODXVHRID6(/(&7
g &UHDWLQJYLHZVWKDWVHOHFWIURPDUUD\VOLFHV

Reading data from an array

7KHUHDUHVHYHQVWHSVUHTXLUHGIRUUHDGLQJGDWDIURPDQDUUD\RUVOLFHRIDQDUUD\
 &UHDWHD6(/(&7VWDWHPHQWWKDWVSHFLILHVVHOHFWLRQRIWKHDUUD\FROXPQ DQGDQ\
RWKHUFROXPQVGHVLUHG LQWKHURZVRILQWHUHVW
 3UHSDUHDQRXWSXW;64/'$VWUXFWXUHWRKROGWKHFROXPQGDWDIRUHDFKURZWKDW
LVIHWFKHG
 3UHSDUHWKH6(/(&7VWDWHPHQWIRUH[HFXWLRQ
 ([HFXWHWKHVWDWHPHQW
 3RSXODWHDQDUUD\GHVFULSWRUZLWKLQIRUPDWLRQGHVFULELQJWKHDUUD\RUDUUD\VOLFH
WREHUHWULHYHG
 )HWFKWKHVHOHFWHGURZVRQHE\RQH
 5HDGDQGSURFHVVWKHDUUD\GDWDIURPHDFKURZ

4 &UHDWLQJWKH6(/(&7VWDWHPHQW
(OLFLWDVWDWHPHQWVWULQJIURPWKHXVHURUFUHDWHRQHWKDWFRQVLVWVRIWKH64/TXHU\WKDWZLOO
VHOHFWURZVFRQWDLQLQJWKHDUUD\GDWDRILQWHUHVW,Q\RXUTXHU\VSHFLI\WKHDUUD\FROXPQQDPH
DQGWKHQDPHVRIDQ\RWKHUFROXPQVFRQWDLQLQJGDWD\RXDUHLQWHUHVWHGLQ)RUH[DPSOHWKH
IROORZLQJFUHDWHVDQ64/TXHU\VWDWHPHQWVWULQJWKDWVHOHFWVDQDUUD\FROXPQQDPHG
48$57B+($'B&17DQGDQRWKHUFROXPQQDPHG'(37B12IURPWKHWDEOH
352-B'(37B%8'*(7

API GUIDE 131

 CHAPTER 8 WORKING WITH ARRAY DATA

char *sel_str =
"SELECT DEPT_NO, QUART_HEAD_CNT FROM PROJ_DEPT_BUDGET \
WHERE year = 1994 AND PROJ_ID = ’VBASE’";

4 3UHSDULQJWKHRXWSXW;64/'$
0RVWTXHULHVUHWXUQRQHRUPRUHURZVRIGDWDUHIHUUHGWRDVDVHOHFWOLVW$QRXWSXW
;64/'$PXVWEHFUHDWHGWRVWRUHWKHFROXPQGDWDIRUHDFKURZWKDWLVIHWFKHG)RUDQDUUD\
FROXPQWKHFROXPQGDWDLVDQLQWHUQDODUUD\LGHQWLILHU DUUD\,' WKDWLVQHHGHGWRDFFHVVWKH
DFWXDOGDWD7RSUHSDUHWKH;64/'$IROORZWKHVHVWHSV
 'HFODUHDYDULDEOHWRKROGWKH;64/'$)RUH[DPSOHWKHIROORZLQJGHFODUDWLRQ
FUHDWHVDQ;64/'$FDOOHG out_sqlda
XSQLDA *out_sqlda;

 $OORFDWHPHPRU\IRUWKH;64/'$XVLQJWKH;64/'$B/(1*7+PDFUR7KH
;64/'$PXVWFRQWDLQRQH;64/9$5VXEVWUXFWXUHIRUHDFKFROXPQWREH
IHWFKHG7KHIROORZLQJVWDWHPHQWDOORFDWHVVWRUDJHIRUDQRXWSXW;64/'$
out_sqlda ZLWKWZR;64/9$5VXEVWUXFWXUHV
out_sqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(2));

 6HWWKHversionILHOGRIWKH;64/'$WR64/'$B9(56,21DQGVHWWKHsqln
ILHOGRIWKH;64/'$WRLQGLFDWHWKHQXPEHURI;64/9$5VXEVWUXFWXUHV
DOORFDWHG
out_sqlda->version = SQLDA_VERSION1;
out_sqlda->sqln = 2;

4 3UHSDULQJWKH6(/(&7VWDWHPHQWIRUH[HFXWLRQ
$IWHUDQ;64/'$LVFUHDWHGIRUKROGLQJWKHFROXPQGDWDIRUHDFKVHOHFWHGURZWKHTXHU\
VWDWHPHQWVWULQJFDQEHSUHSDUHGIRUH[HFXWLRQ)ROORZWKHVHVWHSV
 'HFODUHDQGLQLWLDOL]HDQ64/VWDWHPHQWKDQGOHWKHQDOORFDWHLWZLWK
isc_dsql_allocate_statement()
isc_stmt_handle stmt; /* Declare a statement handle. */
stmt = NULL; /* Set handle to NULL before allocation. */
isc_dsql_allocate_statement(status_vector, &db_handle, &stmt);

 5HDG\WKHVWDWHPHQWVWULQJIRUH[HFXWLRQZLWKisc_dsql_prepare()7KLVFKHFNV
WKHVWULQJ sel_str IRUV\QWD[HUURUVSDUVHVLWLQWRDIRUPDWWKDWFDQEHHIILFLHQWO\
H[HFXWHGDQGVHWVWKHVWDWHPHQWKDQGOH stmt WRUHIHUWRWKLVSDUVHGIRUPDW
7KHVWDWHPHQWKDQGOHLVXVHGLQDODWHUFDOOWRisc_dsql_execute()

132 INTERBASE 5
ACCESSING ARRAY DATA

,I isc_dsql_prepare()LVSDVVHGDSRLQWHUWRWKHRXWSXW;64/'$DVLQWKHIROORZLQJ
H[DPSOHLWZLOOILOOLQPRVWILHOGVRIWKH;64/'$DQGDOOLWV;64/9$5VXEVWUXFWXUHV
ZLWKLQIRUPDWLRQVXFKDVWKHGDWDW\SHOHQJWKDQGQDPHRIWKHFRUUHVSRQGLQJFROXPQV
LQWKHVWDWHPHQW
$VDPSOHFDOOWRisc_dsql_prepare()LV
isc_dsql_prepare(
status_vector,
&trans, /* Set by previous isc_start_transaction() call. */
&stmt, /* Statement handle set by this function call. */
0, /* Specifies statement string is null-terminated. */
sel_str, /* Statement string. */
1, /* XSQLDA version number. */
out_sqlda /* XSQLDA for storing column data. */
);

 6HWXSDQ;64/9$5VWUXFWXUHIRUHDFKFROXPQ6HWWLQJXSDQ;64/9$5
VWUXFWXUHLQYROYHVWKHIROORZLQJVWHSV
)RUFROXPQVZKRVHW\SHVDUHNQRZQDWFRPSLOHWLPH
 6SHFLI\WKHFROXPQ·VGDWDW\SH LILWZDVQRWVHWE\isc_dsql_prepare()DVSUHYLRXVO\
GHVFULEHG 
 3RLQWWKHsqldataILHOGRIWKH;64/9$5WRDQDSSURSULDWHORFDOYDULDEOH
)RUFROXPQVZKRVHW\SHVDUHQRWNQRZQXQWLOUXQWLPH
 &RHUFHWKHLWHP·VGDWDW\SH RSWLRQDO IRUH[DPSOHIURP64/B9$5<,1*WR
64/B7(;7
 '\QDPLFDOO\DOORFDWHORFDOVWRUDJHIRUWKHGDWDSRLQWHGWRE\WKHsqldataILHOGRIWKH
;64/9$5
)RUERWK
3URYLGHD18//YDOXHLQGLFDWRUIRUWKHSDUDPHWHU
à 'DWDUHWULHYDOIRUDUUD\ DQG%ORE FROXPQVLVGLIIHUHQWIURPRWKHUW\SHVRIFROXPQVVRWKH
;64/9$5ILHOGVPXVWEHVHWGLIIHUHQWO\)RUQRQDUUD\ DQGQRQ%ORE FROXPQV
isc_dsql_prepare()VHWVHDFK;64/9$5sqltypeILHOGWRWKHDSSURSULDWHILHOGW\SHDQG
WKHGDWDUHWULHYHGZKHQDVHOHFWOLVWURZ·VGDWDLVIHWFKHGLVSODFHGLQWRWKHsqldataVSDFH
DOORFDWHGIRUWKHFROXPQ)RUDUUD\FROXPQVWKHW\SHLVVHWWR64/B$55$< RU
64/B$55$<LIWKHDUUD\FROXPQLVDOORZHGWREH18// ,QWHU%DVHVWRUHVWKHLQWHUQDO
DUUD\LGHQWLILHU DUUD\,' QRWWKHDUUD\GDWDLQWKHsqldataVSDFHZKHQDURZ·VGDWDLV
IHWFKHGVR\RXPXVWSRLQWsqldataWRDQDUHDWKHVL]HRIDQDUUD\,'7RVHHKRZWRUHWULHYH
WKHDFWXDODUUD\RUDUUD\VOLFHGDWDRQFH\RXKDYHDQDUUD\,'VHH´5HDGLQJDQGSURFHVVLQJ
WKHDUUD\GDWDµRQSDJH 

API GUIDE 133

 CHAPTER 8 WORKING WITH ARRAY DATA

à 7KHIROORZLQJFRGHH[DPSOHLOOXVWUDWHVWKHDVVLJQPHQWVIRUDUUD\DQGQRQDUUD\FROXPQV
ZKRVHW\SHVDUHNQRZQDWFRPSLOHWLPH)RUPRUHLQIRUPDWLRQDERXW'64/DQGWKH
;64/'$DQGZRUNLQJZLWKFROXPQVZKRVHW\SHVDUHXQNQRZQXQWLOUXQWLPHVHH&KDSWHU
´:RUNLQJZLWK'\QDPLF64/µ
ISC_QUAD array_id = 0L;
char dept_no[6];
short flag0, flag1;
out_sqlda->sqlvar[0].sqldata = (char *) dept_no;
out_sqlda->sqlvar[0].sqltype = SQL_TEXT + 1;
out_sqlda->sqlvar[0].sqlind = &flag0;
out_sqlda->sqlvar[1].sqldata = (char *) &array_id;
out_sqlda->sqlvar[1].sqltype = SQL_ARRAY + 1;
out_sqlda->sqlvar[1].sqlind = &flag1;

4 ([HFXWLQJWKHVWDWHPHQW
2QFHWKHTXHU\VWDWHPHQWVWULQJLVSUHSDUHGLWFDQEHH[HFXWHG
isc_dsql_execute(
status_vector,
&trans, /* set by previous isc_start_transaction() call */
&stmt, /* set above by isc_dsql_prepare() */
1, /* XSQLDA version number */
NULL /* NULL since stmt doesn’t have input values */
);

7KLVVWDWHPHQWFUHDWHVDVHOHFWOLVWWKHURZVUHWXUQHGE\H[HFXWLRQRIWKH
VWDWHPHQW

4 3RSXODWLQJWKHDUUD\GHVFULSWRU
7RSUHSDUHDQDUUD\GHVFULSWRUWKDWGHVFULEHVWKHDUUD\RUDUUD\VOLFHWREHUHDGIROORZWKHVH
VWHSV
 &UHDWHWKHDUUD\GHVFULSWRU
ISC_ARRAY_DESC desc;

 )LOOLQWKHGHVFULSWRUZLWKLQIRUPDWLRQUHJDUGLQJWKHDUUD\FROXPQIURPZKLFK
GDWDZLOOEHUHDG'RWKLVHLWKHUE\FDOOLQJRQHRIWKHIXQFWLRQV
isc_array_lookup_bounds()isc_array_lookup_desc()RU
isc_array_set_desc()RUE\GLUHFWO\ILOOLQJLQWKHGHVFULSWRU)RULQIRUPDWLRQRQ
WKHFRQWHQWVRIDUUD\GHVFULSWRUVDQGWKHXVDJHRIWKHVHIXQFWLRQVVHH´$UUD\
GHVFULSWRUVµRQSDJH 
(QVXUHWKHGHVFULSWRUERXQGDULHVDUHVHWWRWKRVHRIWKHVOLFHWREHUHDG

134 INTERBASE 5
ACCESSING ARRAY DATA

,I\RXZDQWWRUHWULHYHDOOWKHDUUD\GDWD WKDWLVQRWMXVWDVPDOOHUVOLFH VHWWKHERXQGDULHV

WRWKHIXOOERXQGDULHVDVLQLWLDOO\GHFODUHGIRUWKHDUUD\FROXPQ7KLV LVJXDUDQWHHGWREH
WKHFDVHLI\RXILOOLQWKHGHVFULSWRUE\FDOOLQJisc_array_lookup_bounds()DVLQ
ISC_ARRAY_DESC desc;
isc_array_lookup_bounds(
status_vector,
&db_handle,
&trans,
"PROJ_DEPT_BUDGET",/* table name */
"QUART_HEAD_CNT", /* array column name */
&desc);

6XSSRVHWKHDUUD\FROXPQ48$57B+($'B&17LVDRQHGLPHQVLRQDODUUD\FRQVLVWLQJ
RIIRXUHOHPHQWVDQGLWZDVGHFODUHGWRKDYHDORZHUVXEVFULSWERXQGRIDQGDQXSSHU
ERXQGRIZKHQLWZDVFUHDWHG7KHQDIWHUWKHDERYHFDOOWR
isc_array_lookup_bounds()WKHDUUD\GHVFULSWRUILHOGVIRUWKHERXQGDULHVFRQWDLQWKH
IROORZLQJLQIRUPDWLRQ
desc.array_desc_bounds[0].array_bound_lower == 1
desc.array_desc_bounds[0].array_bound_upper == 4

,I\RXZDQWWRUHDGMXVWDVOLFHRIWKHDUUD\WKHQPRGLI\WKHXSSHUDQGRUORZHUERXQGV
DSSURSULDWHO\)RUH[DPSOHLI\RXMXVWZDQWWRUHDGWKHILUVWWZRHOHPHQWVRIWKHDUUD\
WKHQPRGLI\WKHXSSHUERXQGWRWKHYDOXHDVLQ
desc.array_desc_bounds[0].array_bound_upper = 2

4 )HWFKLQJVHOHFWHGURZV
$ORRSLQJFRQVWUXFWLVXVHGWRIHWFK LQWRWKHRXWSXW;64/'$ WKHFROXPQGDWDIRUDVLQJOH
URZDWDWLPHIURPWKHVHOHFWOLVWDQGWRSURFHVVHDFKURZEHIRUHWKHQH[WURZLVIHWFKHG(DFK
H[HFXWLRQRIisc_dsql_fetch()IHWFKHVWKHFROXPQGDWDIRUWKHQH[WURZLQWRWKH
FRUUHVSRQGLQJ;64/9$5VWUXFWXUHVRIout_sqlda)RUWKHDUUD\FROXPQWKHDUUD\,'QRW
WKHDFWXDODUUD\GDWDLVIHWFKHG
ISC_STATUS fetch_stat;
long SQLCODE;
. . .
while ((fetch_stat = j
isc_dsql_fetch(status_vector, &stmt, 1, out_sqlda))
== 0)
{
/* Read and process the array data */
}
if (fetch_stat != 100L)
{

API GUIDE 135

 CHAPTER 8 WORKING WITH ARRAY DATA

/* isc_dsql_fetch returns 100 if no more rows remain to be

retrieved */
SQLCODE = isc_sqlcode(status_vector);
isc_print_sqlerror(SQLCODE, status_vector);
return(1);
}

4 5HDGLQJDQGSURFHVVLQJWKHDUUD\GDWD
7RUHDGDQGSURFHVVWKHDUUD\RUDUUD\VOLFHGDWD
 &UHDWHDEXIIHUIRUKROGLQJWKHDUUD\GDWDWREHUHDG0DNHLWODUJHHQRXJKWR
KROGDOOWKHHOHPHQWVLQWKHVOLFHWREHUHDG ZKLFKFRXOGEHWKHHQWLUHDUUD\ )RU
H[DPSOHWKHIROORZLQJGHFODUHVDQDUUD\EXIIHUODUJHHQRXJKWRKROGORQJ
HOHPHQWV
long hcnt[4];

 'HFODUHDVKRUWYDULDEOHIRUVSHFLI\LQJWKHVL]HRIWKHDUUD\EXIIHU
short len;

 6HWWKHYDULDEOHWRWKHEXIIHUOHQJWK
len = sizeof(hcnt);

 5HDGWKHDUUD\RUDUUD\VOLFHGDWDLQWRWKHEXIIHUE\FDOOLQJ
isc_array_get_slice()3URFHVVWKHGDWDUHDG,QWKHIROORZLQJH[DPSOHWKH
DUUD\LVUHDGLQWRWKHhcntDUUD\EXIIHUDQG´SURFHVVLQJµFRQVLVWVRISULQWLQJWKH
GDWD
isc_array_get_slice(
status_vector,
&db_handle,/* set by isc_attach_database()*/
&trans, /* set by isc_start_transaction() */
&array_id, /* array ID put into out_sqlda by isc_dsql_fetch()*/
&desc, /* array descriptor specifying slice to be read */
(void *) hcnt,/* buffer into which data will be read */
(long *) &len/* length of buffer */
);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector);
return(1);
}
/* Make dept_no a null-terminated string */
dept_no[out_sqlda->sqlvar[0].sqllen] = ’\0’;
printf("Department #: %s\n\n", dept_no);

136 INTERBASE 5
ACCESSING ARRAY DATA

printf("\tCurrent head counts: %ld %ld %ld %ld\n",

hcnt[0], hcnt[1], hcnt[2], hcnt[3]);

Writing data to an array

isc_array_put_slice()LVFDOOHGWRZULWHGDWDWRDQDUUD\RUDUUD\VOLFH8VHLWWR
g ,QFOXGHDQHZDUUD\LQDURZWREHLQVHUWHGLQWRDWDEOH
g 5HSODFHWKHFXUUHQWFRQWHQWVRIDQDUUD\FROXPQRIDURZZLWKDQHZDUUD\
g 8SGDWHWKHDUUD\UHIHUHQFHGE\DQDUUD\FROXPQRIDURZE\PRGLI\LQJWKHDUUD\GDWDRUD
VOLFHRIWKHGDWD
7KHHQWU\LQDQDUUD\FROXPQRIDURZGRHVQRWDFWXDOO\FRQWDLQDUUD\GDWD5DWKHULWKDVDQ
DUUD\,'UHIHUULQJWRWKHGDWDZKLFKLVVWRUHGHOVHZKHUH6RWRVHWRUPRGLI\DQDUUD\FROXPQ
\RXQHHGWRVHWRUFKDQJHWKHDUUD\,'VWRUHGLQLW,IDQDUUD\FROXPQFRQWDLQVDQDUUD\,'
DQG\RXPRGLI\WKHFROXPQWRUHIHUWRDGLIIHUHQWDUUD\ RUWRFRQWDLQ18// WKHDUUD\
UHIHUHQFHGE\WKHSUHYLRXVO\VWRUHGDUUD\,'ZLOOEHGHOHWHGGXULQJWKHQH[WJDUEDJH
FROOHFWLRQ
7KHIROORZLQJVWHSVDUHUHTXLUHGWRLQVHUWUHSODFHRUXSGDWHDUUD\GDWD
 3UHSDUHDQDUUD\GHVFULSWRUZLWKLQIRUPDWLRQGHVFULELQJWKHDUUD\ RUVOLFH WREH
ZULWWHQWR
 3UHSDUHDQDUUD\EXIIHUZLWKWKHGDWDWREHZULWWHQ
 3UHSDUHDQDSSURSULDWH'64/VWDWHPHQW7KLVZLOOEHDQ,16(57VWDWHPHQWLI
\RXDUHLQVHUWLQJDQHZURZLQWRDWDEOHRUDQ83'$7(VWDWHPHQWIRUPRGLI\LQJ
DQH[LVWLQJURZ
 &DOOisc_array_put_slice()WRFUHDWHDQHZDUUD\ SRVVLEO\FRS\LQJDQH[LVWLQJ
RQH DQGWRZULWHWKHGDWDIURPWKHDUUD\EXIIHULQWRWKHDUUD\RUDUUD\VOLFH
 $VVRFLDWHWKHQHZDUUD\ZLWKDQDUUD\FROXPQRIWKHWDEOHURZEHLQJPRGLILHG
RULQVHUWHGE\H[HFXWLQJWKH83'$7(RU,16(57VWDWHPHQW7KLVVHWVWKHDUUD\
FROXPQWRFRQWDLQWKHDUUD\,'RIWKHQHZDUUD\

4 3UHSDULQJWKHDUUD\GHVFULSWRU
7RSUHSDUHDQDUUD\GHVFULSWRUWKDWVSHFLILHVWKHDUUD\RUDUUD\VOLFHWREHZULWWHQWRIROORZ
WKHVHVWHSV
 &UHDWHWKHDUUD\GHVFULSWRU
ISC_ARRAY_DESC desc;

API GUIDE 137

 CHAPTER 8 WORKING WITH ARRAY DATA

 )LOOLQWKHGHVFULSWRUZLWKLQIRUPDWLRQUHJDUGLQJWKHDUUD\FROXPQWRZKLFKGDWD
ZLOOEHZULWWHQ'RWKLVHLWKHUE\FDOOLQJRQHRIWKHIXQFWLRQV
isc_array_lookup_bounds()isc_array_lookup_desc()RU
isc_array_set_desc()RUE\GLUHFWO\ILOOLQJLQWKHGHVFULSWRU)RULQIRUPDWLRQRQ
WKHFRQWHQWVRIDUUD\GHVFULSWRUVDQGWKHXVDJHRIWKHVHIXQFWLRQVVHH´$UUD\
GHVFULSWRUVµRQSDJH 
(QVXUHWKHGHVFULSWRUERXQGDULHVDUHVHWWRWKRVHRIWKHVOLFHWREHZULWWHQWR
,I\RXZDQWWRZULWHWRWKHHQWLUHDUUD\ LHQRWMXVWDVPDOOHUVOLFH VHWWKHERXQGDULHVWR
WKHIXOOERXQGDULHVDVLQLWLDOO\GHFODUHGIRUWKHDUUD\FROXPQ7KLV LVJXDUDQWHHGWREHWKH
FDVHLI\RXILOOLQWKHGHVFULSWRUE\FDOOLQJisc_array_lookup_bounds()DVLQ
isc_array_lookup_bounds(
status_vector,
db_handle,
&trans,
"PROJ_DEPT_BUDGET",/* table name */
"QUART_HEAD_CNT", /* array column name */
&desc);
6XSSRVHWKHDUUD\FROXPQ48$57B+($'B&17LVDRQHGLPHQVLRQDODUUD\FRQVLVWLQJ
RIIRXUHOHPHQWVDQGLWZDVGHFODUHGWRKDYHDORZHUVXEVFULSWERXQGRIDQGDQXSSHU
ERXQGRIZKHQLWZDVFUHDWHG7KHQDIWHUDFDOOWR isc_array_lookup_bounds()WKH
DUUD\GHVFULSWRUILHOGVIRUWKHERXQGDULHVFRQWDLQWKHIROORZLQJLQIRUPDWLRQ
desc.array_desc_bounds[0].array_bound_lower == 1
desc.array_desc_bounds[0].array_bound_upper == 4
,I\RXMXVWZDQWWRZULWHWR RUPRGLI\ DVOLFHRIWKHDUUD\WKHQFKDQJHWKHXSSHUDQG
ORZHUERXQGDSSURSULDWHO\)RUH[DPSOHLI\RXMXVWZDQWWRZULWHWRWKHILUVWWZRHOHPHQWV
RIWKHDUUD\WKHQPRGLI\WKHXSSHUERXQGWRWKHYDOXHDVLQ
desc.array_desc_bounds[0].array_bound_upper == 2

4 3UHSDULQJWKHDUUD\EXIIHUZLWKGDWD
&UHDWHDQDUUD\EXIIHUWRKROGWKHGDWDWREHZULWWHQWRWKHDUUD\0DNHLWODUJHHQRXJKWRKROG
DOOWKHHOHPHQWVLQWKHVOLFHWREHZULWWHQ ZKLFKFRXOGEHWKHHQWLUHDUUD\ )RUH[DPSOHWKH
IROORZLQJGHFODUHVDQDUUD\EXIIHUODUJHHQRXJKWRKROGORQJHOHPHQWV
long hcnt[4];

 &UHDWHDYDULDEOHVSHFLI\LQJWKHOHQJWKRIWKHDUUD\EXIIHU
short len;
len = sizeof(hcnt);

 )LOOWKHDUUD\EXIIHUZLWKWKHGDWDWREHZULWWHQ

138 INTERBASE 5
ACCESSING ARRAY DATA

,I\RXDUHFUHDWLQJDQHZDUUD\WKHQILOOWKHEXIIHUZLWKGDWD)RU
H[DPSOH
hcnt[0] = 4;
hcnt[1] = 5;
hcnt[2] = 6;
hcnt[3] = 6;

7RPRGLI\H[LVWLQJDUUD\GDWDLQVWHDGRIFUHDWLQJDQHZRQHWKHQSHUIRUPDOOWKHVWHSV
OLVWHGLQ´5HDGLQJGDWDIURPDQDUUD\µRQSDJH WRUHDGWKHH[LVWLQJDUUD\GDWDLQWRWKH
DUUD\EXIIHU0RGLI\WKHGDWDLQWKHEXIIHU

4 3UHSDULQJWKH83'$7(RU,16(57VWDWHPHQW
7RSUHSDUHDQ83'$7(RU,16(57VWDWHPHQWIRUH[HFXWLRQIROORZWKHVHVWHSV
 (OLFLWDQ83'$7(RU,16(57VWDWHPHQWVWULQJIURPWKHXVHURUFUHDWHRQHIRU
LQVHUWLQJDQHZURZRUXSGDWLQJWKHURZ V FRQWDLQLQJWKHDUUD\FROXPQ V RI
LQWHUHVW)RUH[DPSOHWKHIROORZLQJVWDWHPHQWLVIRUXSGDWLQJWKHDUUD\
FROXPQQDPHG48$57B+($'B&17LQWKHVSHFLILHGURZRIWKHWDEOH
352-B'(37B%8'*(77KHGHSDUWPHQWQXPEHUDQGTXDUWHUO\KHDGFRXQWV
DUHDVVXPHGWREHVXSSOLHGDWUXQWLPH
char *upd_str =
"UPDATE PROJ_DEPT_BUDGET SET QUART_HEAD_CNT = ? WHERE \
YEAR = 1994 AND PROJ_ID = "MKTPR" AND DEPT_NO = ?";

$VDQH[DPSOHRIDQ,16(57VWDWHPHQWWKHIROORZLQJLVIRULQVHUWLQJDQHZURZLQWRWKH
352-B'(37B%8'*(7WDEOHZLWKFROXPQGDWDVXSSOLHGDWUXQWLPH
char *upd_str =
"INSERT INTO PROJ_DEPT_BUDGET (YEAR, PROJ_ID, DEPT_NO, \
QUART_HEAD_CNT) VALUES (?, ?, ?, ?)";

7KHUHPDLQLQJVWHSVUHIHURQO\WR83'$7(VWDWHPHQWVEXWWKHDFWLRQVDSSO\WR,16(57
VWDWHPHQWVDVZHOO
 'HFODUHDYDULDEOHWRKROGWKHLQSXW;64/'$QHHGHGWRVXSSO\SDUDPHWHU
YDOXHVWRWKH83'$7(VWDWHPHQWDWUXQWLPH)RUH[DPSOHWKHIROORZLQJ
GHFODUDWLRQFUHDWHVDQ;64/'$FDOOHGin_sqlda
XSQLDA *in_sqlda;

API GUIDE 139

 CHAPTER 8 WORKING WITH ARRAY DATA

 $OORFDWHPHPRU\IRUWKHLQSXW;64/'$XVLQJWKH;64/'$B/(1*7+
PDFUR7KH;64/'$PXVWFRQWDLQRQH;64/9$5VXEVWUXFWXUHIRUHDFK
SDUDPHWHUWREHSDVVHGWRWKH83'$7(VWDWHPHQW7KHIROORZLQJVWDWHPHQW
DOORFDWHVVWRUDJHIRUDQLQSXW;64/'$ in_sqlda ZLWKWZR;64/9$5
VXEVWUXFWXUHV
in_sqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(2));

 6HWWKHversionILHOGRIWKH;64/'$WR64/'$B9(56,21DQGVHWWKHsqln
ILHOGWRLQGLFDWHWKHQXPEHURI;64/9$5VWUXFWXUHVDOORFDWHG
in_sqlda->version = SQLDA_VERSION1;
in_sqlda->sqln = 2;

 6HWXSWKH;64/9$5VWUXFWXUHLQWKH;64/'$IRUHDFKSDUDPHWHUWREH
SDVVHG6HWWLQJXSDQ;64/9$5VWUXFWXUHLQYROYHVWKHIROORZLQJVWHSV
 6SHFLI\WKHLWHP·VGDWDW\SH
 )RUSDUDPHWHUVZKRVHW\SHVDUHNQRZQDWFRPSLOHWLPHSRLQWWKHsqldataILHOGRIWKH
;64/9$5WRDQDSSURSULDWHORFDOYDULDEOHWKDWZLOOFRQWDLQWKHGDWDWREHSDVVHG
 )RUSDUDPHWHUVZKRVHW\SHVDUHQRWNQRZQXQWLOUXQWLPHDOORFDWHORFDOVWRUDJHIRUWKH
GDWDSRLQWHGWRE\WKHsqldataILHOGRIWKH;64/9$5
 6SHFLI\WKHQXPEHURIE\WHVRIGDWD
'DWDVWRUDJHIRUDUUD\ DQG%ORE FROXPQVLVGLIIHUHQWIURPRWKHUW\SHVRIFROXPQVVR
WKH;64/9$5ILHOGVPXVWEHVHWGLIIHUHQWO\)RUQRQDUUD\ DQGQRQ%ORE FROXPQV
LQSXWSDUDPHWHUGDWDFRPHVIURPWKHVSDFHSRLQWHGWRE\ sqldata)RUDUUD\FROXPQVVHW
WKHW\SHWR64/B$55$< RU64/B$55$<LIWKHDUUD\FROXPQLVDOORZHGWREH
18// 7KHDSSOLFDWLRQPXVWVWRUHVSDFHIRUWKHLQWHUQDODUUD\LGHQWLILHUQRWWKHDUUD\
GDWDLQWKHsqldataVSDFH6HHWKHIROORZLQJVHFWLRQVWRFUHDWHRUPRGLI\DQDUUD\VWRUH
LWVDUUD\,'LQWKHsqldataVSDFHDQGWKHQDVVRFLDWHWKHDFWXDODUUD\GDWDZLWKWKHFROXPQ
7KHIROORZLQJFRGHH[DPSOHLOOXVWUDWHVWKHDVVLJQPHQWVIRURQH7(;7FROXPQDQGRQH
DUUD\FROXPQZKHUHWKHFROXPQW\SHVDUHNQRZQDWFRPSLOHWLPH
#define NUMLEN 4
char dept_no[NUMLEN + 1];
ISC_QUAD array_id;
in_sqlda->sqlvar[0].sqldata = &array_id;
in_sqlda->sqlvar[0].sqltype = SQL_ARRAY + 1;
in_sqlda->sqlvar[0].sqllen = sizeof(ISC_QUAD);
in_sqlda->sqlvar[1].sqldata = dept_no;
in_sqlda->sqlvar[1].sqltype = SQL_TEXT;
in_sqlda->sqlvar[1].sqllen = 4;

140 INTERBASE 5
ACCESSING ARRAY DATA

7KHdept_noYDULDEOHVKRXOGEHDVVLJQHGDYDOXHDWUXQWLPH XQOHVVWKHYDOXHLVNQRZQ
DWFRPSLOHWLPH 7KHarray_idYDULDEOHVKRXOGEHVHWWRUHIHUWRWKHQHZO\FUHDWHGDUUD\
DVGHVFULEHGLQWKHIROORZLQJVHFWLRQV
)RUH[DPSOHVRIKDQGOLQJGDWDZKRVHW\SHVDUHQRWNQRZQXQWLOUXQWLPHVHH&KDSWHU
´:RUNLQJZLWK'\QDPLF64/µ

4 &DOOLQJLVFBDUUD\BSXWBVOLFH
7KHIROORZLQJVWHSVDUHUHTXLUHGWRVWRUHWKHGDWDLQWRDQDUUD\RUDUUD\VOLFH
 'HFODUHDQDUUD\,'
ISC_QUAD array_id; /* Declare an array ID. */

 ,QLWLDOL]HWKHDUUD\,',I\RXDUHFUHDWLQJDQHZDUUD\WREHLQVHUWHGLQWRDQHZ
URZRUWRUHSODFHDQH[LVWLQJDUUD\WKHQVLPSO\LQLWLDOL]HWKHDUUD\,'WR18//
array_id = NULL;/* Set handle to NULL before using it */

,I\RXDUHPRGLI\LQJDQH[LVWLQJDUUD\WKHQIROORZWKHVWHSVOLVWHGXQGHU´5HDGLQJ'DWD
IURPDQ$UUD\µWRUHDGWKHH[LVWLQJDUUD\,'LQWRarray_id
 &DOO isc_array_put_slice(),Q\RXUFDOO\RXSDVVWKHDUUD\,' HLWKHUWKHDUUD\
,'RIDQH[LVWLQJDUUD\RU18//IRUDQHZDUUD\ LQWKHarray_idYDULDEOH<RX
DOVRSDVVWKHEXIIHURIGDWDWREHZULWWHQDQGDGHVFULSWRUVSHFLI\LQJWKHDUUD\
VOLFHWRZKLFKWKHGDWDEHORQJV
:KHQisc_array_put_slice()LVFDOOHGZLWKDQDUUD\,'RIDQH[LVWLQJDUUD\LWFUHDWHVD
QHZDUUD\ZLWKWKHVDPHFKDUDFWHULVWLFVDVWKHVSHFLILHGDUUD\DQGFRSLHVWKHH[LVWLQJDUUD\
GDWDWRWKHQHZDUUD\7KHQisc_array_put_slice()ZULWHVWKHGDWDIURPWKHDUUD\EXIIHU
WRWKHQHZDUUD\ RUVOLFHRIWKHDUUD\ SHUWKHERXQGVVSHFLILHGLQWKHDUUD\GHVFULSWRU
DQGUHWXUQVLQWKHVDPHarray_idYDULDEOHWKHDUUD\,'RIWKHQHZDUUD\
:KHQisc_array_put_slice()LVFDOOHGZLWKD18//DUUD\,'LWFUHDWHVDQHZHPSW\DUUD\
ZLWKFKDUDFWHULVWLFVDVGHFODUHGIRUWKHDUUD\FROXPQZKRVHQDPHDQGWDEOHQDPHDUH
VSHFLILHGLQWKHDUUD\GHVFULSWRUSDVVHGWRisc_array_put_slice(),WWKHQZULWHVWKHGDWD
IURPWKHDUUD\EXIIHUWRWKHQHZDUUD\ RUVOLFHRIWKHDUUD\ DQGUHWXUQVLQWKHarray_id
YDULDEOHWKHDUUD\,'RIWKHQHZDUUD\
1RWHWKDWLQERWKFDVHVDQHZDUUD\LVFUHDWHGDQGLWVDUUD\,'LVUHWXUQHGLQWKHarray_id
YDULDEOH7KHDUUD\LVWHPSRUDU\XQWLODQ83'$7(RU,16(57VWDWHPHQWLVH[HFXWHGWR
DVVRFLDWHWKHDUUD\ZLWKDSDUWLFXODUFROXPQRIDSDUWLFXODUURZ

API GUIDE 141

 CHAPTER 8 WORKING WITH ARRAY DATA

<RXFDQPDNHDVLQJOHFDOOWRisc_array_put_slice()WRZULWHDOOWKHGDWDWRWKHDUUD\2U
\RXPD\FDOOisc_array_put_slice()PXOWLSOHWLPHVWRVWRUHGDWDLQWRYDULRXVVOLFHVRIWKH
DUUD\,QWKLVFDVHHDFKFDOOWRisc_array_put_slice()DIWHUWKHILUVWFDOOVKRXOGSDVV WKH
DUUD\,'RIWKHWHPSRUDU\DUUD\:KHQisc_array_put_slice() LVFDOOHGZLWK WKHDUUD\,'
RIDWHPSRUDU\DUUD\LWFRSLHVWKHVSHFLILHGGDWDWRWKHVSHFLILHGVOLFHRIWKHWHPSRUDU\
DUUD\EXWGRHVQRWFUHDWHDQHZDUUD\
7KHIROORZLQJLVDVDPSOHFDOOWR isc_array_put_slice()
isc_array_put_slice(
status_vector,
&db_handle,
&trans,
&array_id, /* array ID (NULL, or existing array’s array ID) */
&desc, /* array descriptor describing where to write data */
hcnt, /* array buffer containing data to write to array */
&len /* length of array buffer */
);
7KLVFDOOFUHDWHVDQHZDUUD\FRSLHVWKHGDWDLQhcntWRWKHQHZDUUD\ RUVOLFHRIWKHDUUD\ 
DVVLJQVWKHDUUD\DQDUUD\,'DQGVHWVarray_idWRSRLQWWRWKHDUUD\,'

,03257$17 array_idVKRXOGEHWKHYDULDEOHSRLQWHGWRE\WKHsqldataILHOGRIWKH83'$7( RU

,16(57 VWDWHPHQWLQSXWSDUDPHWHUWKDWVSHFLILHVWKHDUUD\FROXPQWREHXSGDWHG7KXV
ZKHQWKH,16(57RU83'$7(VWDWHPHQWLVH[HFXWHGWKLVQHZDUUD\·VDUUD\,'ZLOOEHXVHG
WRVHWRUXSGDWHWKHDUUD\FROXPQWRUHIHUWRWKHQHZDUUD\

4 $VVRFLDWLQJWKHQHZDUUD\ZLWKWKHDUUD\FROXPQ
([HFXWHWKH83'$7(VWDWHPHQWWRDVVRFLDWHWKHQHZDUUD\ZLWKWKHDUUD\FROXPQLQWKHURZ
VHOHFWHGE\WKHVWDWHPHQW
isc_dsql_execute_immediate(
status_vector,
&db_handle,
&trans,
0, /* indicates string to execute is null-terminated */
upd_str, /* UPDATE statement string to be executed */
1, /* XSQLDA version number */
in_sqlda /* XSQLDA supplying parameters to UPDATE statement */
);

7KLVVHWVWKHDUUD\FROXPQLQWKHURZVSHFLILHGLQWKH83'$7(VWDWHPHQWWRFRQWDLQWKH
DUUD\,'RIWKHQHZDUUD\7KHDUUD\,'FRPHVIURPWKHarray_idYDULDEOHSRLQWHGWRE\WKH
LQBVTOGDSDUDPHWHUFRUUHVSRQGLQJWRWKHDUUD\FROXPQ

142 INTERBASE 5
ACCESSING ARRAY DATA

,IWKHDUUD\FROXPQLQWKHVSHFLILHGURZFRQWDLQVWKHDUUD\,'RIDGLIIHUHQWDUUD\EHIRUHWKH
83'$7(VWDWHPHQWLVH[HFXWHGWKHQWKHFROXPQLVPRGLILHGWRFRQWDLQWKHQHZDUUD\,'
DQGWKHDUUD\UHIHUHQFHGE\WKHSUHYLRXVO\VWRUHGDUUD\,'ZLOOEHGHOHWHGGXULQJWKHQH[W
JDUEDJHFROOHFWLRQ

Deleting an array
7KHUHDUHWKUHHZD\VWRGHOHWHDQDUUD\
 'HOHWHWKHURZFRQWDLQLQJWKHDUUD\<RXFDQXVH'64/WRH[HFXWHD'(/(7(
VWDWHPHQW
 5HSODFHWKHDUUD\ZLWKDGLIIHUHQWRQHDVGHVFULEHGDERYH,IDQDUUD\FROXPQ
FRQWDLQVDQDUUD\,'DQG\RXPRGLI\WKHFROXPQWRUHIHUWRDGLIIHUHQWDUUD\WKH
DUUD\UHIHUHQFHGE\WKHSUHYLRXVO\VWRUHGDUUD\,'ZLOOEHGHOHWHGGXULQJWKHQH[W
JDUEDJHFROOHFWLRQ
 5HVHWWR18//WKHFROXPQUHIHUULQJWRWKHDUUD\)RUH[DPSOHXVH'64/WR
H[HFXWHDVWDWHPHQWOLNHWKHIROORZLQJZKHUH/$1*8$*(B5(4LVDQDUUD\
FROXPQ
"UPDATE JOB SET LANGUAGE_REQ = NULL \
WHERE JOB_CODE = "SA12" AND JOB_GRADE = 10"

7KHDUUD\UHIHUHQFHGE\WKHSUHYLRXVO\VWRUHGDUUD\,'ZLOOEHGHOHWHGGXULQJWKHQH[W
JDUEDJHFROOHFWLRQ

API GUIDE 143

 CHAPTER

Working with Conversions

Chapter9
9
,QWHU%DVHXVHVDSURSULHWDU\IRUPDWIRULQWHUQDOVWRUDJHRI'$7(GDWDEXWSURYLGHVWKH
IROORZLQJ$3,FDOOVIRUWUDQVODWLQJWRDQGIURPWKLVIRUPDW
g isc_decode_date()WRFRQYHUWWKH,QWHU%DVHLQWHUQDOGDWHIRUPDWWRWKH&WLPHVWUXFWXUH
g isc_encode_date WRFRQYHUWWKH&WLPHVWUXFWXUHWRWKHLQWHUQDO,QWHU%DVHGDWHIRUPDW
7KHVHFDOOVPHUHO\WUDQVODWH'$7(GDWDEHWZHHQIRUPDWVWKH\GRQRWUHDGRUZULWH'$7(
GDWDGLUHFWO\'$7(GDWDLVUHDGIURPDQGZULWWHQWRWKHGDWDEDVHXVLQJVWDQGDUG'64/
V\QWD[SURFHVVHGZLWKWKHisc_dsqlIDPLO\RI$3,FDOOV
,QWHU%DVHDOVRUHTXLUHVWKDWQXPEHUVHQWHUHGLQGDWDEDVHDQGWUDQVDFWLRQSDUDPHWHUEXIIHUV
EHLQDJHQHULFIRUPDWZLWKWKHOHDVWVLJQLILFDQWE\WHODVW6LJQHGQXPEHUVUHTXLUHWKHVLJQWR
EHLQWKHODVWE\WH6\VWHPVWKDWUHSUHVHQWQXPEHUVZLWKWKHPRVWVLJQLILFDQWE\WHODVWPXVW
XVHWKHisc_vax_integer()$3,IXQFWLRQWRUHYHUVHWKHE\WHRUGHURIQXPEHUVHQWHUHGLQ
GDWDEDVHSDUDPHWHUEXIIHUV '3%V DQGWUDQVDFWLRQSDUDPHWHUEXIIHUV 73%V :KHQ
QXPHULFLQIRUPDWLRQLVUHWXUQHGE\LQIRUPDWLRQFDOOVRQWKHVHV\VWHPVisc_vax_integer()
PXVWEHXVHGRQFHDJDLQWRUHYHUVHWKHE\WHRUGHULQJ
)RUPRUHLQIRUPDWLRQDERXWXVLQJ'64/WRUHDGDQGZULWHGDWDVHH&KDSWHU´:RUNLQJ
ZLWK'\QDPLF64/µ

145
 CHAPTER 9 WORKING WITH CONVERSIONS

Converting dates from InterBase to C format

7RVHOHFWDGDWHIURPDWDEOHDQGFRQYHUWLWWRDIRUPXVDEOHLQD&ODQJXDJHSURJUDPIROORZ
WKHVHVWHSV
 &UHDWHDKRVWYDULDEOHIRUD&WLPHVWUXFWXUH0RVW&DQG&FRPSLOHUVSURYLGH
DW\SHGHIGHFODUDWLRQWPIRUWKH&WLPHVWUXFWXUHLQWKHWLPHKKHDGHUILOH7KH
IROORZLQJ&FRGHLQFOXGHVWKDWKHDGHUILOHDQGGHFODUHVDYDULDEOHRIW\SHWP
#include <time.h>
#include "ibase.h"
. . .
struct tm hire_time;
. . .
Note 7RFUHDWHKRVWODQJXDJHWLPHVWUXFWXUHVLQODQJXDJHVRWKHUWKDQ&DQG&VHHWKH
KRVWODQJXDJHUHIHUHQFHPDQXDO
 &UHDWHDKRVWYDULDEOHRIW\SH,6&B48$')RUH[DPSOHWKHKRVWYDULDEOH
GHFODUDWLRQPLJKWORRNOLNHWKLV
ISC_QUAD hire_date;

7KH,6&B48$'VWUXFWXUHLVGHFODUHGLQLEDVHKEXWWKHSURJUDPPHUPXVWGHFODUHDFWXDO
KRVWODQJXDJHYDULDEOHVRIW\SH,6&B48$'
 5HWULHYHDGDWHIURPDWDEOHLQWRWKH,6&B48$'YDULDEOH
 &RQYHUWWKH,6&B48$'YDULDEOHLQWRDQXPHULF&IRUPDWZLWKWKH,QWHU%DVH
IXQFWLRQisc_decode_date()7KLVIXQFWLRQLVDOVRGHFODUHGLQLEDVHK
isc_decode_date()UHTXLUHVWZRSDUDPHWHUVWKHDGGUHVVRIWKH,6&B48$'
KRVWODQJXDJHYDULDEOHDQGWKHDGGUHVVRIWKHWPKRVWODQJXDJHYDULDEOH)RU
H[DPSOHWKHIROORZLQJFRGHIUDJPHQWFRYHUWVKLUHBGDWHWRKLUHBWLPH
isc_decode_date(&hire_date, &hire_time);

Converting dates from C to InterBase format

7RLQVHUWDGDWHLQDWDEOHLWPXVWEHFRQYHUWHGIURPWKHKRVWODQJXDJHIRUPDWLQWR,QWHU%DVH
IRUPDWDQGWKHQVWRUHG7RSHUIRUPWKHFRQYHUVLRQDQGLQVHUWLRQLQD&SURJUDPIROORZ
WKHVHVWHSV
 &UHDWHDKRVWYDULDEOHIRUD&WLPHVWUXFWXUH0RVW&DQG&FRPSLOHUVSURYLGH
DW\SHGHIGHFODUDWLRQWPIRUWKH&WLPHVWUXFWXUHLQWKHWLPHKKHDGHUILOH7KH
IROORZLQJ&FRGHLQFOXGHVWKDWKHDGHUILOHDQGGHFODUHVDWPYDULDEOHKLUHBWLPH
#include <time.h>;

146 INTERBASE 5
REVERSING BYTE ORDER OF NUMBERS WITH ISC_VAX_INTEGER( )

. . .
struct tm hire_time;
. . .

7RFUHDWHKRVWODQJXDJHWLPHVWUXFWXUHVLQODQJXDJHVRWKHUWKDQ&DQG&VHHWKH
KRVWODQJXDJHUHIHUHQFHPDQXDO
 &UHDWHDKRVWYDULDEOHRIW\SH,6&B48$'IRUXVHE\,QWHU%DVH)RUH[DPSOH
WKHKRVWYDULDEOHGHFODUDWLRQPLJKWORRNOLNHWKLV
ISC_QUAD mydate;

7KH,6&B48$'VWUXFWXUHLVGHFODUHGLQLEDVHKEXWWKHSURJUDPPHUPXVWGHFODUHDFWXDO
KRVWODQJXDJHYDULDEOHVRIW\SH,6&B48$'
 3XWGDWHDQGWLPHLQIRUPDWLRQLQWRKLUHBWLPH
 8VHWKH,QWHU%DVHisc_encode_date()IXQFWLRQWRFRQYHUWWKHLQIRUPDWLRQLQ
KLUHBWLPHLQWR,QWHU%DVHLQWHUQDOIRUPDWDQGVWRUHWKDWIRUPDWWHGLQIRUPDWLRQLQ
WKH,6&B48$'KRVWYDULDEOH KLUHBGDWHLQWKHH[DPSOH 7KLVIXQFWLRQLVDOVR
GHFODUHGLQLEDVHK
isc_encode_date()UHTXLUHVWZRSDUDPHWHUVWKHDGGUHVVRIWKH&WLPHVWUXFWXUHDQGWKH
DGGUHVVRIWKH,6&B48$'KRVWODQJXDJHYDULDEOH)RUH[DPSOHWKHIROORZLQJFRGH
FRQYHUWVKLUHBWLPHWRKLUHBGDWH
isc_encode_date(&hire_time, &hire_date);
 ,QVHUWWKHGDWHLQWRDWDEOH

Reversing byte order of numbers with isc_vax_integer( )

,QWHU%DVHH[SHFWVWKDWQXPEHUVHQWHUHGLQGDWDEDVHDQGWUDQVDFWLRQSDUDPHWHUEXIIHUVEHLQ
DJHQHULFIRUPDWZLWKWKHOHDVWVLJQLILFDQWE\WHODVW6LJQHGQXPEHUVUHTXLUHWKHVLJQWREHLQ
WKHODVWE\WH6\VWHPVWKDWUHSUHVHQWQXPEHUVZLWKWKHPRVWVLJQLILFDQWE\WHODVWPXVWXVHWKH
isc_vax_integer()$3,IXQFWLRQWRUHYHUVHWKHE\WHRUGHURIQXPEHUVHQWHUHGLQ'3%VDQG
73%V:KHQQXPHULFLQIRUPDWLRQLVUHWXUQHGE\LQIRUPDWLRQFDOOVRQWKHVHV\VWHPV
isc_vax_integer()PXVWEHXVHGRQFHDJDLQWRUHYHUVHWKHE\WHRUGHULQJ7KHV\QWD[IRU
isc_vax_integer()LV
ISC_LONG isc_vax_integer( char *buffer, short length);
EXIIHULVDFKDUSRLQWHUWRWKHLQWHJHUWRFRQYHUWDQGOHQJWKLVWKHVL]HLQE\WHVRIWKHLQWHJHU
9DOLGOHQJWKVDUH VKRUW  LQW DQG ORQJ 7KHIROORZLQJFRGHUHYHUVHVWKHE\WHYDOXH
LQDUHVXOWEXIIHU
#include "ibase.h"
. . .

API GUIDE 147

 CHAPTER 9 WORKING WITH CONVERSIONS

for(p = res_buffer; *p != isc_info_end;)

{
p++;
length = isc_vax_integer(p, 2);
}

148 INTERBASE 5
 CHAPTER

Handling Error Conditions

Chapter10
10
7KLVFKDSWHUGHVFULEHVKRZWRVHWXSDQHUURUVWDWXVYHFWRUZKHUH,QWHU%DVHFDQVWRUH
UXQWLPHHUURULQIRUPDWLRQDQGKRZWRXVH$3,IXQFWLRQVWRKDQGOHDQGUHSRUWHUURUV
7KHIROORZLQJWDEOHVXPPDUL]HVWKH$3,IXQFWLRQVIRUKDQGOLQJHUURUV

Function Purpose
isc_interprete() Capture InterBase error messages to a buffer
isc_print_sqlerror() Display an SQL error message
isc_print_status() Display InterBase error messages
isc_sqlcode() Set the value of SQLCODE
isc_sql_interprete() Capture an SQL error message to a buffer
TABLE 10.1 Error-handling functions

149
 CHAPTER 10 HANDLING ERROR CONDITIONS

Setting up an error status vector

0RVW$3,IXQFWLRQVUHWXUQVWDWXVLQIRUPDWLRQWKDWLQGLFDWHVVXFFHVVRUIDLOXUH7KH
LQIRUPDWLRQUHWXUQHGLVGHULYHGIURPWKHVHFRQGDUUD\HOHPHQWRIWKHHUURUVWDWXVYHFWRU
ZKHUH,QWHU%DVHUHSRUWVHUURUFRQGLWLRQV7KHHUURUVWDWXVYHFWRULVGHFODUHGLQDSSOLFDWLRQV
DVDQDUUD\RIORQJLQWHJHUVXVLQJWKHIROORZLQJV\QWD[
#include <ibase.h>
. . .
ISC_STATUS status_vector[20];

,6&B67$786LVDGHILQHLQLEDVHKSURYLGHGIRUSURJUDPLQJFRQYHQLHQFHDQGSODWIRUP
LQGHSHQGHQFH

Using information in the status vector

:KHWKHURUQRWDQHUURURFFXUVGXULQJWKHH[HFXWLRQRIDQ$3,FDOO,QWHU%DVHORDGVWKHHUURU
VWDWXVYHFWRUZLWKVWDWXVLQIRUPDWLRQ,QIRUPDWLRQFRQVLVWVRIRQHRUPRUH,QWHU%DVHHUURU
FRGHVDQGHUURULQIRUPDWLRQWKDWFDQEHXVHGWREXLOGDQHUURUPHVVDJHKRQHGWRDVSHFLILF
HUURU
$QDSSOLFDWLRQFDQFKHFNWKHVWDWXVYHFWRUDIWHUWKHH[HFXWLRQRIPRVW$3,FDOOVWRGHWHUPLQH
WKHLUVXFFHVVRUIDLOXUH,IDQHUURUFRQGLWLRQLVUHSRUWHGDSSOLFDWLRQVFDQ
g 'LVSOD\,QWHU%DVHHUURUPHVVDJHVXVLQJisc_print_status()
g 6HWDQ64/&2'(YDOXHFRUUHVSRQGLQJWRDQ,QWHU%DVHHUURUXVLQJisc_sqlcode()DQG
GLVSOD\WKH64/&2'(DQGDQ64/HUURUPHVVDJHXVLQJisc_print_sqlerror()
g %XLOGLQGLYLGXDO,QWHU%DVHHUURUPHVVDJHVLQDEXIIHUZLWKisc_interprete()7KHEXIIHUPXVW
EHSURYLGHGE\WKHDSSOLFDWLRQ8VLQJDEXIIHUHQDEOHVDQDSSOLFDWLRQWRSHUIRUPDGGLWLRQDO
PHVVDJHSURFHVVLQJ IRUH[DPSOHVWRULQJPHVVDJHVLQDQHUURUORJILOH 7KLVDELOLW\LV
HVSHFLDOO\XVHIXORQZLQGRZLQJV\VWHPVWKDWGRQRWSHUPLWGLUHFWVFUHHQZULWHV
g &DSWXUHDQ64/HUURUPHVVDJHLQDEXIIHUZLWKisc_sql_interprete()7KHEXIIHUPXVWEH
SURYLGHGE\WKHDSSOLFDWLRQ
g 3DUVHIRUDQGUHDFWWRVSHFLILF,QWHU%DVHHUURUFRGHVLQWKHVWDWXVYHFWRU

150 INTERBASE 5
USING INFORMATION IN THE STATUS VECTOR

Checking the status vector for errors

$3,IXQFWLRQVWKDWUHWXUQLQIRUPDWLRQLQWKHVWDWXVYHFWRUDUHGHFODUHGLQLEDVHKDVUHWXUQLQJ
DQ,6&B67$786SRLQWHU)RUH[DPSOHWKHIXQFWLRQSURWRW\SHIRU
isc_prepare_transaction()LVGHFODUHGDV
ISC_STATUS ISC_EXPORT isc_prepare_transaction(
ISC_STATUS ISC_FAR *,
isc_tr_handle ISC_FAR *);

7RFKHFNWKHVWDWXVYHFWRUIRUHUURUFRQGLWLRQVDIWHUWKHH[HFXWLRQRIDIXQFWLRQH[DPLQHWKH
ILUVWHOHPHQWRIWKHVWDWXVYHFWRUWRVHHLILWLVVHWWRDQGLIVRH[DPLQHWKHVHFRQGHOHPHQW
WRVHHLILWLVQRW$QRQ]HURYDOXHLQWKHVHFRQGHOHPHQWLQGLFDWHVDQHUURUFRQGLWLRQ7KH
IROORZLQJ&FRGHIUDJPHQWLOOXVWUDWHVKRZWRFKHFNWKHVWDWXVYHFWRUIRUDQHUURUFRQGLWLRQ
#include <ibase.h>
. . .
ISC_STATUS status_vector[20];
. . .
/* Assume an API call returning status information is called here. */
if (status_vector[0] == 1 && status_vector[1] > 0)
{
/* Handle error condition here. */
;
}

,IDQHUURUFRQGLWLRQLVGHWHFWHG\RXFDQXVH$3,IXQFWLRQVLQDQHUURUKDQGOLQJURXWLQHWR
GLVSOD\HUURUPHVVDJHVFDSWXUHWKHHUURUPHVVDJHVLQDEXIIHURUSDUVHWKHVWDWXVYHFWRUIRU
SDUWLFXODUHUURUFRGHV
'LVSOD\RUFDSWXUHRIHUURUPHVVDJHVLVRQO\RQHSDUWRIDQHUURUKDQGOLQJURXWLQH8VXDOO\
WKHVHURXWLQHVDOVRUROOEDFNWUDQVDFWLRQVDQGVRPHWLPHVWKH\FDQUHWU\IDLOHGRSHUDWLRQV

Displaying InterBase error messages

8VHisc_print_status()WRGLVSOD\,QWHU%DVHHUURUPHVVDJHVRQWKHVFUHHQ7KLVIXQFWLRQ
SDUVHVWKHVWDWXVYHFWRUWREXLOGDOODYDLODEOHHUURUPHVVDJHVWKHQXVHVWKH&printf()IXQFWLRQ
WRZULWHWKHPHVVDJHVWRWKHGLVSOD\isc_print_status()UHTXLUHVRQHSDUDPHWHUDSRLQWHUWR
DVWDWXVYHFWRUFRQWDLQLQJHUURULQIRUPDWLRQ)RUH[DPSOHWKHIROORZLQJFRGHIUDJPHQWFDOOV
isc_print_status()DQGUROOVEDFNDWUDQVDFWLRQRQHUURU
#include <ibase.h>
. . .
ISC_STATUS status_vector[20];

API GUIDE 151

 CHAPTER 10 HANDLING ERROR CONDITIONS

isc_tr_handle trans;
. . .
trans = 0L;
. . .
/* Assume a transaction, trans, is started here. */
/* Assume an API call returning status information is called here. */
if (status_vector[0] == 1 && status_vector[1] > 0)
{
isc_print_status(status_vector);
isc_rollback_transaction(status_vector, &trans);
}

,03257$17 2QZLQGRZLQJV\VWHPVWKDWGRQRWSHUPLWGLUHFWVFUHHQZULWHVZLWKprintf()XVH
isc_interprete()WRFDSWXUHHUURUPHVVDJHVWRDEXIIHU

7,3 )RUDSSOLFDWLRQVWKDWXVHWKHG\QDPLF64/ '64/ $3,IXQFWLRQVHUURUVVKRXOGEH

GLVSOD\HGXVLQJ64/FRQYHQWLRQV8VHisc_sqlcode()DQGisc_print_sqlerror()LQVWHDGRI
isc_print_status()

Capturing InterBase error messages

8VHisc_interprete()WREXLOGDQHUURUPHVVDJHIURPLQIRUPDWLRQLQWKHVWDWXVYHFWRUDQG
VWRUHLWLQDQDSSOLFDWLRQGHILQHGEXIIHUZKHUHLWFDQEHIXUWKHUPDQLSXODWHG&DSWXULQJ
PHVVDJHVLQDEXIIHULVXVHIXOZKHQDSSOLFDWLRQV
g 5XQXQGHUZLQGRZLQJV\VWHPVWKDWGRQRWSHUPLWGLUHFWVFUHHQZULWHV
g 5HTXLUHPRUHFRQWURORYHUPHVVDJHGLVSOD\WKDQLVSRVVLEOHZLWKisc_print_status()
g 6WRUHDUHFRUGRIDOOHUURUPHVVDJHVLQDORJILOH
g 0DQLSXODWHRUIRUPDWHUURUPHVVDJHVIRUGLVSOD\RUSDVVWKHPWRDZLQGRZLQJV\VWHP·V
GLVSOD\URXWLQHV
isc_interprete()UHWULHYHVDQGIRUPDWVDVLQJOHHUURUPHVVDJHHDFKWLPHLWLVFDOOHG:KHQDQ
HUURURFFXUVWKHVWDWXVYHFWRUXVXDOO\FRQWDLQVPRUHWKDQRQHHUURUPHVVDJH7RUHWULHYHDOO
UHOHYDQWHUURUPHVVDJHV\RXPXVWPDNHUHSHDWHGFDOOVWRisc_interprete()
*LYHQERWKWKHORFDWLRQRIDEXIIHUDQGWKHDGGUHVVRIWKHVWDWXVYHFWRUisc_interprete()
EXLOGVDQHUURUPHVVDJHIURPWKHLQIRUPDWLRQLQWKHVWDWXVYHFWRUSXWVWKHIRUPDWWHGVWULQJ
LQWKHEXIIHUZKHUHDQDSSOLFDWLRQFDQPDQLSXODWHLWDQGDGYDQFHVWKHVWDWXVYHFWRUSRLQWHU
WRWKHVWDUWRIWKHQH[WFOXVWHURIHUURULQIRUPDWLRQisc_interprete()UHTXLUHVWZR
SDUDPHWHUVWKHDGGUHVVRIDQDSSOLFDWLRQEXIIHUWRKROGIRUPDWWHGPHVVDJHRXWSXWDQGD
SRLQWHUWRWKHVWDWXVYHFWRUDUUD\

152 INTERBASE 5
USING INFORMATION IN THE STATUS VECTOR

,03257$17 1HYHUSDVVWKHVWDWXVYHFWRUDUUD\GLUHFWO\WRisc_interprete()(DFKWLPHLWLVFDOOHG
isc_interprete()DGYDQFHVWKHSRLQWHUWRWKHVWDWXVYHFWRUWRWKHQH[WHOHPHQWFRQWDLQLQJ
QHZPHVVDJHLQIRUPDWLRQ%HIRUHFDOOLQJisc_interprete()EHVXUHWRVHWWKHSRLQWHUWRWKH
VWDUWLQJDGGUHVVRIWKHVWDWXVYHFWRU
7KHIROORZLQJFRGHGHPRQVWUDWHVDQHUURUKDQGOLQJURXWLQHWKDWPDNHVUHSHDWHGFDOOVWR
isc_interprete()WRUHWULHYHHUURUPHVVDJHVIURPWKHVWDWXVYHFWRULQDEXIIHURQHDWDWLPH
VRWKH\FDQEHZULWWHQWRDORJILOH
#include <ibase.h>
. . .
ISC_STATUS status_vector[20];
isc_tr_handle trans;
long *pvector;
char msg[512];
FILE *efile; /* Code fragment assumes pointer to an open file. */
trans = 0L;
. . .
/* Error-handling routine starts here. */
/* Always set pvector to point to start of status_vector. */
pvector = status_vector;
/* Retrieve first message. */
isc_interprete(msg, &pvector);
/* Write first message from buffer to log file. */
fprintf(efile, "%s\n", msg);
msg[0] = ’-’; /* Append leading hyphen to secondary messages. */
/* Look for more messages and handle in a loop. */
while(isc_interprete(msg + 1, &pvector)) /* More? */
fprintf(efile, "%s\n", msg); /* If so, write it to the log. */
fclose(efile); /* All done, so close the log file. */
isc_rollback(status_vector, &trans);
return(1);
. . .
Note 7KLVFRGHIUDJPHQWDVVXPHVWKDWWKHORJILOHLVSURSHUO\GHFODUHGDQGRSHQHGHOVHZKHUH
LQWKHDSSOLFDWLRQEHIRUHFRQWUROLVSDVVHGWRWKLVHUURUKDQGOHU

7,3 )RUDSSOLFDWLRQVWKDWXVHWKHG\QDPLF64/ '64/ $3,IXQFWLRQVHUURUVVKRXOGEH

EXIIHUHGXVLQJ64/FRQYHQWLRQV8VHisc_sqlcode()DQGisc_sql_interprete()LQVWHDGRI
isc_interprete()

API GUIDE 153

 CHAPTER 10 HANDLING ERROR CONDITIONS

Setting an SQLCODE value on error

)RU'64/DSSOLFDWLRQVHUURUFRQGLWLRQVVKRXOGEHFDVWLQWHUPVRI64/FRQYHQWLRQV64/
DSSOLFDWLRQVW\SLFDOO\UHSRUWHUURUVWKURXJKDYDULDEOH64/&2'(GHFODUHGE\DQ
DSSOLFDWLRQ7RWUDQVODWHDQ,QWHU%DVHHUURUFRGHLQWR64/&2'(IRUPDWXVH
isc_sqlcode()7KLVIXQFWLRQVHDUFKHVWKHHUURUVWDWXVYHFWRUIRUDQ,QWHU%DVHHUURUFRGHWKDW
FDQEHWUDQVODWHGLQWRDQ64/HUURUFRGHDQGSHUIRUPVWKHWUDQVODWLRQ2QFH64/&2'(LV
VHWWKHRWKHU$3,IXQFWLRQVIRUKDQGOLQJ64/HUURUVisc_print_sqlerror()DQG
isc_sql_interprete()FDQEHFDOOHG
isc_sqlcode()UHTXLUHVRQHSDUDPHWHUDSRLQWHUWRWKHVWDWXVYHFWRU,WUHWXUQVDORQJYDOXH
FRQWDLQLQJDQ64/HUURUFRGH7KHIROORZLQJFRGHLOOXVWUDWHVWKHXVHRIWKLVIXQFWLRQ
#include <ibase.h>;
. . .
long SQLCODE; /* Declare the SQL error code variable. */
ISC_STATUS status_vector[20];
. . .
if (status_vector[0] == 1 && status_vector[1] > 0)
{
SQLCODE = isc_sqlcode(status_vector);
isc_print_sqlerror(SQLCODE, status_vector)
. . .
}

,IVXFFHVVIXOisc_sqlcode()UHWXUQVWKHILUVWYDOLG64/HUURUFRGHGHFRGHGIURPWKHVWDWXV
YHFWRU,IQRYDOLG64/HUURUFRGHLVIRXQGisc_sqlcode()UHWXUQV

Displaying SQL error messages

$3,DSSOLFDWLRQVWKDWSURYLGHD'64/LQWHUIDFHWRHQGXVHUVVKRXOGXVH
isc_print_sqlerror()WRGLVSOD\64/HUURUFRGHVDQGFRUUHVSRQGLQJHUURUPHVVDJHVRQWKH
VFUHHQ:KHQSDVVHGDYDULDEOHFRQYHQWLRQDOO\QDPHG64/&2'(FRQWDLQLQJDQ64/HUURU
FRGHDQGDSRLQWHUWRWKHVWDWXVYHFWRU isc_print_sqlerror()SDUVHVWKHVWDWXVYHFWRUWREXLOG
DQ64/HUURUPHVVDJHWKHQXVHVWKH&printf()IXQFWLRQWRZULWHWKH64/&2'(YDOXHDQG
PHVVDJHWRWKHGLVSOD\)RUH[DPSOHWKHIROORZLQJFRGHIUDJPHQWFDOOVisc_print_sqlerror()
DQGUROOVEDFNDWUDQVDFWLRQRQHUURU
#include <ibase.h>
. . .
ISC_STATUS status_vector[20];
isc_tr_handle trans;
long SQLCODE;

154 INTERBASE 5
USING INFORMATION IN THE STATUS VECTOR

. . .
trans = 0L;
. . .
/* Assume a transaction, trans, is started here. */
/* Assume an API call returning status information is called here. */
if (status_vector[0] == 1 && status_vector[1] > 0)
{
SQLCODE = isc_sqlcode(status_vector);
isc_print_sqlerror(SQLCODE, status_vector);
isc_rollback_transaction(status_vector, &trans);
}

,03257$17 2QZLQGRZLQJV\VWHPVWKDWGRQRWSHUPLWGLUHFWVFUHHQZULWHVZLWKprintf()XVH
isc_sql_interprete()WRFDSWXUHHUURUPHVVDJHVWRDEXIIHU

Capturing SQL error messages

8VHisc_sql_interprete()WREXLOGDQ64/HUURUPHVVDJHEDVHGRQDVSHFLILF64/HUURUFRGH
DQGVWRUHLWLQDEXIIHUGHILQHGE\DQDSSOLFDWLRQ&DSWXULQJPHVVDJHVLQDEXIIHULVXVHIXO
ZKHQDSSOLFDWLRQV
g 5XQXQGHUZLQGRZLQJV\VWHPVWKDWGRQRWSHUPLWGLUHFWVFUHHQZULWHV
g 6WRUHDUHFRUGRIDOOHUURUPHVVDJHVLQDORJILOH
g 0DQLSXODWHRUIRUPDWHUURUPHVVDJHVIRUGLVSOD\RUSDVVWKHPWRDZLQGRZLQJV\VWHP·V
GLVSOD\URXWLQHV
isc_sql_interprete()UHTXLUHVWKUHHSDUDPHWHUVDYDOLG64/HUURUFRGHXVXDOO\SDVVHGDVD
YDULDEOHQDPHG64/&2'(DEXIIHUZKHUHWKH64/PHVVDJHVKRXOGEHVWRUHGDQGWKHVL]H
RIWKHEXIIHU7KHIROORZLQJFRGHLOOXVWUDWHVKRZWKLVIXQFWLRQPLJKWEHFDOOHGWREXLOGD
PHVVDJHVWULQJDQGVWRUHLWLQDORJILOH
#include <ibase.h>
. . .
ISC_STATUS status_vector[20];
isc_tr_handle trans;
long SQLCODE;
char msg[512];
FILE *efile; /* Code fragment assumes pointer to an open file. */
trans = 0L;
. . .
/* Assume a transaction, trans, is started here. */
/* Assume an API call returning status information is called here. */
. . .

API GUIDE 155

 CHAPTER 10 HANDLING ERROR CONDITIONS

/* Error-handling routine starts here. */

if (status_vector[0] == 1 && status_vector[1] > 0)
{
SQLCODE = isc_sqlcode(status_vector);
isc_sql_interprete(SQLCODE, msg, 512);
fprintf(efile, "%s\n", msg);
isc_rollback_transaction(status_vector, &trans);
return(1);
}
Note 7KLVFRGHIUDJPHQWDVVXPHVWKDWWKHORJILOHLVSURSHUO\GHFODUHGDQGRSHQHGHOVHZKHUH
LQWKHDSSOLFDWLRQEHIRUHFRQWUROLVSDVVHGWRWKLVHUURUKDQGOHU

Parsing the status vector

,QWHU%DVHVWRUHVHUURULQIRUPDWLRQLQWKHVWDWXVYHFWRULQFOXVWHUVRIWZRRUWKUHHORQJV7KH
ILUVWFOXVWHULQWKHVWDWXVYHFWRUDOZD\VLQGLFDWHVWKHSULPDU\FDXVHRIWKHHUURU6XEVHTXHQW
FOXVWHUVPD\FRQWDLQVXSSRUWLQJLQIRUPDWLRQDERXWWKHHUURUIRUH[DPSOHVWULQJVRUQXPEHUV
IRUGLVSOD\LQDQDVVRFLDWHGHUURUPHVVDJH7KHDFWXDOQXPEHURIFOXVWHUVXVHGWRUHSRUW
VXSSRUWLQJLQIRUPDWLRQYDULHVIURPHUURUWRHUURU
,QPDQ\FDVHVDGGLWLRQDOHUURUVPD\EHUHSRUWHGLQWKHVWDWXVYHFWRU$GGLWLRQDOHUURUVDUH
UHSRUWHGLPPHGLDWHO\IROORZLQJWKHILUVWHUURUDQGLWVVXSSRUWLQJLQIRUPDWLRQLIDQ\7KHILUVW
FOXVWHUIRUHDFKDGGLWLRQDOHUURUPHVVDJHLGHQWLILHVWKHHUURU6XEVHTXHQWFOXVWHUVPD\FRQWDLQ
VXSSRUWLQJLQIRUPDWLRQDERXWWKHHUURU

4 +RZWKHVWDWXVYHFWRULVSDUVHG
7KH,QWHU%DVHHUURUKDQGOLQJURXWLQHVisc_print_status()DQGisc_interprete()XVH
URXWLQHVZKLFKDXWRPDWLFDOO\SDUVHHUURUPHVVDJHLQIRUPDWLRQLQWKHVWDWXVYHFWRUZLWKRXW
UHTXLULQJ\RXWRNQRZDERXWLWVVWUXFWXUH,I\RXSODQWRZULWH\RXURZQURXWLQHVWRUHDGDQG
UHDFWWRWKHFRQWHQWVRIWKHVWDWXVYHFWRU\RXQHHGWRNQRZKRZWRLQWHUSUHWLW
7KHNH\WRSDUVLQJWKHVWDWXVYHFWRULVWRGHFLSKHUWKHPHDQLQJRIWKHILUVWORQJLQHDFKFOXVWHU
EHJLQQLQJZLWKWKHILUVWFOXVWHULQWKHYHFWRU

4 0HDQLQJRIWKHILUVWORQJLQDFOXVWHU
7KHILUVWORQJLQDQ\FOXVWHULVDQXPHULFGHVFULSWRU%\H[DPLQLQJWKHQXPHULFGHVFULSWRUIRUDQ\
FOXVWHU\RXFDQDOZD\VGHWHUPLQHWKH
g 7RWDOQXPEHURIORQJVLQWKHFOXVWHU
g .LQGRILQIRUPDWLRQUHSRUWHGLQWKHUHPDLQGHURIWKHFOXVWHU

156 INTERBASE 5
USING INFORMATION IN THE STATUS VECTOR

g 6WDUWLQJORFDWLRQRIWKHQH[WFOXVWHULQWKHVWDWXVYHFWRU

Interpretation of 1st long in a cluster

Longs in
Value cluster Meaning
0 — End of error information in the status vector
1 2 Second long is an InterBase error code
2 2 Second long is the address of string used as a replaceable parameter in a generic InterBase
error message
3 3 Second long is the length, in bytes, of a variable-length string provided by the operating
system (most often this string is a file name); third long is the address of the string
4 2 Second long is a number used as a replaceable parameter in a generic InterBase error
message
5 2 Second long is the address of an error message string requiring no further processing
before display
6 2 Second long is a VAX/VMS error code
7 2 Second long is a Unix error code
8 2 Second long is an Apollo Domain error code
9 2 Second long is an MS-DOS or OS/2 error code.
10 2 Second long is an HP MPE/XL error code.
11 2 Second long is an HP MPE/XL IPC error code.
12 2 Second long is a NeXT/Mach error code.
Note: As InterBase is adapted to run on other hardware and software platforms, additional numeric
descriptors for specific platform and operating system error codes may be added to the end of this list.
TABLE 10.2 Interpretation of status vector clusters

%\LQFOXGLQJLEDVHKDWWKHVWDUWRI\RXUVRXUFHFRGH\RXFDQXVHDVHULHVRIGHILQHVWR
VXEVWLWXWHIRUKDUGFRGHGQXPHULFGHVFULSWRUVLQWKHVWDWXVYHFWRUSDUVLQJURXWLQHV\RXZULWH
7KHDGYDQWDJHVRIXVLQJWKHVHGHILQHVRYHUKDUGFRGLQJWKHGHVFULSWRUVDUH
g <RXUFRGHZLOOEHHDVLHUWRUHDG
g &RGHPDLQWHQDQFHZLOOEHHDVLHUVKRXOGWKHQXPEHULQJVFKHPHIRUQXPHULFGHVFULSWRUV
FKDQJHLQDIXWXUHUHOHDVHRI,QWHU%DVH

API GUIDE 157

 CHAPTER 10 HANDLING ERROR CONDITIONS

7KHIROORZLQJWDEOHOLVWVWKHGHILQHHTXLYDOHQWVRIHDFKQXPHULFGHVFULSWRU

Value #define Value #define

0 isc_arg_end 8 isc_arg_domain
1 isc_arg_gds 9 isc_arg_dos
2 isc_arg_string 10 isc_arg_mpexl
3 isc_arg_cstring 11 isc_arg_mpexl_ipc
4 isc_arg_number 15 isc_arg_next_mach
5 isc_arg_interpreted 16 isc_arg_netware
6 isc_arg_vms 17 isc_arg_win32
7 isc_arg_unix
TABLE 10.3 #defines for status vector numeric descriptors

)RUDQH[DPSOHRIFRGHWKDWXVHVWKHVHGHILQHVVHH´6WDWXVYHFWRUSDUVLQJH[DPSOHµRQ
SDJH 

4 0HDQLQJRIWKHVHFRQGORQJLQDFOXVWHU
7KHVHFRQGORQJLQDFOXVWHULVDOZD\VRQHRIILYHLWHPV
g $Q,QWHU%DVHHUURUFRGH VWORQJ  
g $VWULQJDGGUHVV VWORQJ RU 
g $VWULQJOHQJWK VWORQJ  
g $QXPHULFYDOXH VWORQJ  
g $QRSHUDWLQJV\VWHPHUURUFRGH VWORQJ! 

INTERBASE ERROR CODES

,QWHU%DVHHUURUFRGHVKDYHWZRXVHV)LUVWWKH\DUHXVHGLQWHUQDOO\E\,QWHU%DVHIXQFWLRQVWR
EXLOGDQGGLVSOD\GHVFULSWLYHHUURUPHVVDJHVWULQJV)RUH[DPSOHisc_interprete()FDOOV
DQRWKHUIXQFWLRQZKLFKXVHVWKH,QWHU%DVHHUURUFRGHWRUHWULHYHDEDVHHUURUPHVVDJHIURP
ZKLFKLWEXLOGVDQHUURUPHVVDJHVWULQJ\RXFDQGLVSOD\RUVWRUHLQDORJILOH
6HFRQGO\ZKHQ\RXZULWH\RXURZQHUURUKDQGOLQJURXWLQH\RXFDQH[DPLQHWKHVWDWXVYHFWRU
GLUHFWO\WUDSSLQJIRUDQGUHDFWLQJWRVSHFLILF,QWHU%DVHHUURUFRGHV

158 INTERBASE 5
USING INFORMATION IN THE STATUS VECTOR

:KHQWKHVHFRQGORQJRIDFOXVWHULVDQ,QWHU%DVHHUURUFRGHWKHQVXEVHTXHQWFOXVWHUVPD\
FRQWDLQDGGLWLRQDOSDUDPHWHUVIRUWKHHUURUPHVVDJHVWULQJDVVRFLDWHGZLWKWKHHUURUFRGH)RU
H[DPSOHDJHQHULF,QWHU%DVHHUURUPHVVDJHPD\FRQWDLQDUHSODFHDEOHVWULQJSDUDPHWHUIRU
WKHQDPHRIWKHWDEOHZKHUHDQHUURURFFXUVRULWPD\FRQWDLQDUHSODFHDEOHQXPHULF
SDUDPHWHUIRUWKHFRGHRIWKHWULJJHUZKLFKWUDSSHGWKHHUURUFRQGLWLRQ
,I\RXZULWH\RXURZQSDUVLQJURXWLQHV\RXPD\QHHGWRH[DPLQHDQGXVHWKHVHDGGLWLRQDO
FOXVWHUVRIHUURULQIRUPDWLRQ

STRING ADDRESSES
6WULQJDGGUHVVHVSRLQWWRHUURUPHVVDJHWH[W:KHQWKHILUVWORQJLQWKHFOXVWHULV
LVFBDUJBVWULQJ WKHDGGUHVVSRLQWHGWRRIWHQFRQWDLQVWKHQDPHRIWKHGDWDEDVHWDEOHRU
FROXPQDIIHFWHGE\WKHHUURU,QWKHVHFDVHV,QWHU%DVHIXQFWLRQVZKLFKEXLOGHUURUPHVVDJH
VWULQJVUHSODFHDSDUDPHWHULQDJHQHULF,QWHU%DVHHUURUPHVVDJHZLWKWKHVWULQJSRLQWHGWRE\
WKLVDGGUHVV2WKHUWLPHVWKHDGGUHVVSRLQWVWRDQHUURUPHVVDJHKDUGFRGHGLQDGDWDEDVH
WULJJHU
:KHQWKHILUVWORQJLQWKHFOXVWHULV LVFBDUJBLQWHUSUHWHG WKHDGGUHVVSRLQWVWRDWH[WPHVVDJH
ZKLFKUHTXLUHVQRIXUWKHUSURFHVVLQJEHIRUHUHWULHYDO6RPHWLPHVWKLVPHVVDJHPD\EH
KDUGFRGHGLQ,QWHU%DVHLWVHOIDQGRWKHUWLPHVLWPD\EHDV\VWHPOHYHOHUURUPHVVDJH
,QHLWKHURIWKHVHFDVHV,QWHU%DVHIXQFWLRQVVXFKDVisc_print_status()DQG isc_interprete()
FDQIRUPDWDQGGLVSOD\WKHUHVXOWLQJHUURUPHVVDJHIRU\RX

STRING LENGTH INDICATORS

:KHQWKHILUVWORQJLQDFOXVWHULV LVFBDUJBFVWULQJ WKHQXPHULFYDOXHLQWKHVHFRQGORQJ
LQGLFDWHVWKHOHQJWKLQE\WHVRIDPHVVDJHVWULQJZKRVHDGGUHVVLVVWRUHGLQWKHWKLUGORQJLQ
WKHFOXVWHU7KLVVWULQJUHTXLUHVWUDQVODWLRQLQWRDVWDQGDUGQXOOWHUPLQDWHG&VWULQJEHIRUH
GLVSOD\

NUMERIC VALUES
$QXPHULFYDOXHKDVGLIIHUHQWPHDQLQJGHSHQGLQJXSRQWKHYDOXHRIWKHQXPHULFGHVFULSWRU
LQWKHILUVWORQJRIDFOXVWHU,IWKHILUVWORQJLV LVFBDUJBQXPEHU DQXPHULFYDOXHLVXVHGE\
,QWHU%DVHIXQFWLRQVWRUHSODFHQXPHULFSDUDPHWHUVLQJHQHULF,QWHU%DVHHUURUPHVVDJHV
GXULQJPHVVDJHEXLOGLQJ)RULQVWDQFHZKHQDQLQWHJULW\HUURURFFXUV,QWHU%DVHVWRUHVWKH
FRGHRIWKHWULJJHUZKLFKGHWHFWVWKHSUREOHPDVDQXPHULFYDOXHLQWKHVWDWXVYHFWRU:KHQ
DQ,QWHU%DVHIXQFWLRQOLNHisc_interprete()EXLOGVWKHHUURUPHVVDJHVWULQJIRUWKLVHUURULW
LQVHUWVWKHQXPHULFYDOXHIURPWKHVWDWXVYHFWRU LQWRWKHJHQHULF,QWHU%DVHLQWHJULW\HUURU
PHVVDJHVWULQJWRPDNHLWPRUHVSHFLILF

API GUIDE 159

 CHAPTER 10 HANDLING ERROR CONDITIONS

OPERATING SYSTEM ERROR CODES

,IWKHILUVWORQJLQDFOXVWHULVJUHDWHUWKDQWKHQXPHULFYDOXHLQWKHVHFRQGORQJLVDQHUURU
FRGHVSHFLILFWRDSDUWLFXODUSODWIRUPRURSHUDWLQJV\VWHP,QWHU%DVHIXQFWLRQVVKRXOGQRWEH
XVHGWRUHWULHYHDQGGLVSOD\WKHVSHFLILFSODWIRUPRURSHUDWLQJV\VWHPHUURUPHVVDJH&RQVXOW
\RXURSHUDWLQJV\VWHPPDQXDOIRULQIRUPDWLRQRQKRZWRKDQGOHVXFKHUURUV

4 0HDQLQJRIWKHWKLUGORQJLQDFOXVWHU
,IWKHILUVWORQJLQDFOXVWHULV LVFBDUJBFVWULQJ WKHFOXVWHU·VWRWDOOHQJWKLVWKUHHORQJV7KH
WKLUGORQJDOZD\VFRQWDLQVWKHDGGUHVVRIDPHVVDJHVWULQJUHTXLULQJWUDQVODWLRQLQWRDVWDQGDUG
QXOOWHUPLQDWHG&VWULQJEHIRUHGLVSOD\6XFKDVWULQJLVRIWHQDILOHRUSDWKQDPH,QWHU%DVH
IXQFWLRQVOLNHisc_interprete()DXWRPDWLFDOO\KDQGOHWKLVWUDQVODWLRQIRU\RX

4 6WDWXVYHFWRUSDUVLQJH[DPSOH
7KHIROORZLQJ&H[DPSOHLOOXVWUDWHVDVLPSOHEUXWHIRUFHSDUVLQJRIWKHVWDWXVYHFWRU7KH
FRGHIRUFHVDQHUURUFRQGLWLRQ7KHHUURUKDQGOLQJEORFNSDUVHVWKHVWDWXVYHFWRUDUUD\FOXVWHU
E\FOXVWHUSULQWLQJWKHFRQWHQWVRIHDFKFOXVWHUDQGLQWHUSUHWLQJLWIRU\RX
#include <ibase.h>
. . .
ISC_STATUS status_vector[20];
main()
{
int done, v; /* end of args?, index into vector */
int c, extra; /* cluster count, 3 long cluster flag */
static char *meaning[] = {"End of error information",
"n InterBase error code"," string address"," string length",
" numeric value"," system code"};
/* Assume database is connected and transaction started here. */
if (status_vector[0] == 1 && status_vector[1] > 0)
error_exit();
. . .
}
void error_exit(void)
{
done = v = 0;
c = 1;
while (!done)
{
extra = 0;
printf("Cluster %d:\n", c);
printf("Status vector %d: %ld: ", v, status_vector[v]);
if (status_vector[v] != gds_arg_end)

160 INTERBASE 5
USING INFORMATION IN THE STATUS VECTOR

printf("Next long is a");

switch (status_vector[v++])
{
case gds_arg_end:
printf("%s\n", meaning[0]);
done = 1;
break;
case gds_arg_gds:
printf("%s\n", meaning[1]);
break;
case gds_arg_string:
case gds_arg_interpreted:
printf("%s\n", meaning[2]);
break;
case gds_arg_number:
printf("%s\n", meaning[4]);
break;
case gds_arg_cstring:
printf("%s\n", meaning[3]);
extra = 1;
break;
default:
printf("%s\n", meaning[5]);
break;
}
if (!done)
{
printf("Status vector %d: %ld", v, status_vector[v]);
v++;/* advance vector pointer */
c++;/* advance cluster count */
if (extra)
{
printf(": Next long is a %s\n", meaning[2]);
printf("Status vector: %d: %ld\n\n", v,
status_vector[v]);
v++;
}
else
printf("\n\n");
}
}
isc_rollback_transaction(status_vector, &trans);
isc_detach_database(&db1);

API GUIDE 161

 CHAPTER 10 HANDLING ERROR CONDITIONS

return(1);
}

+HUHLVDVDPSOHRIWKHRXWSXWIURPWKLVSURJUDP
Cluster 1:
Status vector 0: 1: Next long is an InterBase error code
Status vector 1: 335544342
Cluster 2:
Status vector 2: 4: Next long is a numeric value
Status vector 3: 1
Cluster 3:
Status vector 4: 1: Next long is an InterBase error code
Status vector 5: 335544382
Cluster 4:
Status vector 6: 2: Next long is a string address
Status vector 7: 156740
Cluster 5:
Status vector 8: 0: End of error information
7KLVRXWSXWLQGLFDWHVWKDWWZR,QWHU%DVHHUURUVRFFXUUHG7KHILUVWHUURUFRGHLV
7KHHUURUSULQWLQJURXWLQHVisc_print_status()DQGisc_interprete(),XVHWKH,QWHU%DVH
HUURUFRGHWRUHWULHYHDFRUUHVSRQGLQJEDVHHUURUPHVVDJH7KHEDVHHUURUPHVVDJHFRQWDLQV
SODFHKROGHUVIRUUHSODFHDEOHSDUDPHWHUV)RUHUURUFRGHWKHEDVHHUURUPHVVDJH
VWULQJLV
"action cancelled by trigger (%ld) to preserve data integrity"

7KLVHUURUPHVVDJHXVHVDUHSODFHDEOHQXPHULFSDUDPHWHUOG
,QWKLVFDVHWKHQXPHULFYDOXHWRXVHIRUUHSODFHPHQWLVVWRUHGLQWKHVHFRQGORQJRIWKH
VHFRQGFOXVWHU:KHQWKHHUURUSULQWLQJURXWLQHLQVHUWVWKHSDUDPHWHULQWRWKHPHVVDJHLW
GLVSOD\VWKHPHVVDJH
action cancelled by trigger (1) to preserve data integrity

7KHVHFRQGHUURUFRGHLV7KHEDVHPHVVDJHUHWULHYHGIRUWKLVHUURUFRGHLV
"%s"
,QWKLVFDVHWKHHQWLUHPHVVDJHWREHGLVSOD\HGFRQVLVWVRIDUHSODFHDEOHVWULQJ7KHVHFRQG
ORQJRIWKHIRXUWKFOXVWHUFRQWDLQVWKHDGGUHVVRIWKHUHSODFHPHQWVWULQJ7KLVLVDQ
HUURUPHVVDJHGHILQHGLQWKHWULJJHUWKDWFDXVHGWKHHUURU:KHQWKHHUURUSULQWLQJURXWLQH
LQVHUWVWKHPHVVDJHIURPWKHWULJJHULQWRWKHEDVHPHVVDJHLWGLVSOD\VWKHUHVXOWLQJPHVVDJH
-Department name is missing.

162 INTERBASE 5
USING INFORMATION IN THE STATUS VECTOR

Note 7KLVVDPSOHSURJUDPLVRQO\PHDQWWRLOOXVWUDWHWKHVWUXFWXUHRIWKHVWDWXVYHFWRUDQG
LWVFRQWHQWV:KLOHWKHHUURUKDQGOLQJURXWLQHLQWKLVSURJUDPPLJKWVHUYHDVDOLPLWHG
GHEXJJLQJWRROIRUDSURJUDPXQGHUGHYHORSPHQWLWGRHVQRWSURYLGHXVHIXOLQIRUPDWLRQIRU
HQGXVHUV2UGLQDULO\HUURUKDQGOLQJEORFNVLQDSSOLFDWLRQVVKRXOGLQWHUSUHWHUURUVGLVSOD\
H[SODQDWRU\HUURUPHVVDJHVDQGWDNHFRUUHFWLYHDFWLRQLIDSSURSULDWH
)RUH[DPSOHLIWKHHUURUKDQGOLQJURXWLQHLQWKHVDPSOHSURJUDPKDGFDOOHG
isc_print_status()WRGLVSOD\WKHHUURUPHVVDJHVDVVRFLDWHGZLWKWKHVHFRGHVWKHIROORZLQJ
PHVVDJHVZRXOGKDYHEHHQGLVSOD\HG
action cancelled by trigger (1) to preserve data integrity
-Department name is missing.

API GUIDE 163

 CHAPTER

Working with Events

Chapter11
11
7KLVFKDSWHUGHVFULEHVKRZWRZRUNZLWKHYHQWVDPHVVDJHSDVVHGIURPDWULJJHURUVWRUHG
SURFHGXUHWRDQDSSOLFDWLRQWRDQQRXQFHWKHRFFXUUHQFHRIDVSHFLILHGFRQGLWLRQRUDFWLRQ
XVXDOO\DGDWDEDVHFKDQJHVXFKDVDQLQVHUWLRQPRGLILFDWLRQRUGHOHWLRQRIDUHFRUG,W
H[SODLQVKRZWRVHWXSHYHQWEXIIHUVDQGXVHWKHIROORZLQJ$3,IXQFWLRQVWRPDNH
V\QFKURQRXVDQGDV\QFKURQRXVHYHQWFDOOV,QWKHIROORZLQJWDEOHIXQFWLRQVDUHOLVWHGLQWKH
RUGHUWKH\W\SLFDOO\DSSHDULQDQDSSOLFDWLRQ

Function Purpose
isc_event_block() Allocate event parameter buffers
isc_wait_for_event() Wait for a synchronous event to be posted
isc_que_events() Set up an asynchronous event and return to application processing
isc_event_counts() Determine the change in values of event counters in the event parameter
buffer
isc_cancel_events() Cancel interest in an event
TABLE 11.1 API event functions

)RUDV\QFKURQRXVHYHQWVWKLVFKDSWHUDOVRGHVFULEHVKRZWRFUHDWHDQDV\QFKURQRXVWUDS
$67 DIXQFWLRQWKDWUHVSRQGVWRSRVWHGHYHQWV

165
 CHAPTER 11 WORKING WITH EVENTS

Understanding the event mechanism

7KH,QWHU%DVHHYHQWPHFKDQLVPFRQVLVWVRIIRXUSDUWV
g 7KH,QWHU%DVHHQJLQHWKDWPDLQWDLQVDQHYHQWTXHXHDQGQRWLILHVDSSOLFDWLRQVZKHQDQHYHQW
RFFXUV
g (YHQWSDUDPHWHUEXIIHUVVHWXSE\DQDSSOLFDWLRQZKHUHLWFDQUHFHLYHQRWLILFDWLRQRIHYHQWV
g $QDSSOLFDWLRQWKDWUHJLVWHUVLQWHUHVWLQRQHRUPRUHVSHFLILHGQDPHGHYHQWVDQGHLWKHUZDLWV
IRUQRWLILFDWLRQWRRFFXU V\QFKURQRXVHYHQW RUSDVVHVDSRLQWHUWRDQ$67IXQFWLRQWKDW
KDQGOHVQRWLILFDWLRQVVRWKDWDSSOLFDWLRQSURFHVVLQJFDQFRQWLQXHLQWKHPHDQWLPH
DV\QFKURQRXVHYHQW 
g $WULJJHURUVWRUHGSURFHGXUHWKDWQRWLILHVWKHHQJLQHWKDWDVSHFLILFQDPHGHYHQWKDV
RFFXUUHG1RWLILFDWLRQLVFDOOHGSRVWLQJ
7KH,QWHU%DVHHYHQWPHFKDQLVPHQDEOHVDSSOLFDWLRQVWRUHVSRQGWRDFWLRQVDQGGDWDEDVH
FKDQJHVPDGHE\RWKHUFRQFXUUHQWO\UXQQLQJDSSOLFDWLRQVZLWKRXWWKHQHHGIRUWKRVH
DSSOLFDWLRQVWRFRPPXQLFDWHGLUHFWO\ZLWKRQHDQRWKHUDQGZLWKRXWLQFXUULQJWKHH[SHQVHRI
&38WLPHUHTXLUHGIRUSHULRGLFSROOLQJWRGHWHUPLQHLIDQHYHQWKDVRFFXUUHG
)RULQIRUPDWLRQDERXWFUHDWLQJWULJJHUVDQGVWRUHGSURFHGXUHVWKDWSRVWHYHQWVVHHWKH'DWD
'HILQLWLRQ*XLGH

Event parameter buffers

,IDQDSSOLFDWLRQLVWRUHFHLYHQRWLILFDWLRQDERXWHYHQWVLWPXVWVHWXSWZRLGHQWLFDOO\VL]HG
HYHQWSDUDPHWHUEXIIHUV (3%V XVLQJisc_event_block()7KHILUVWEXIIHUHYHQWBEXIIHULV
XVHGWRKROGWKHFRXQWRIHYHQWRFFXUUHQFHVEHIRUHWKHDSSOLFDWLRQUHJLVWHUVDQLQWHUHVWLQWKH
HYHQW7KHVHFRQGEXIIHUUHVXOWBEXIIHULVVXEVHTXHQWO\ILOOHGLQZLWKDQXSGDWHGFRXQWRIHYHQW
RFFXUUHQFHVZKHQDQHYHQWRILQWHUHVWWRWKHDSSOLFDWLRQRFFXUV$VHFRQG$3,IXQFWLRQ
isc_event_counts()GHWHUPLQHVWKHGLIIHUHQFHVEHWZHHQLWHPFRXQWVLQWKHVHEXIIHUVWR
GHWHUPLQHZKLFKHYHQWRUHYHQWVRFFXUUHG
)RUPRUHLQIRUPDWLRQDERXWVHWWLQJXSDQGXVLQJ(3%VVHH´&UHDWLQJ(3%VZLWK
LVFBHYHQWBEORFN µRQSDJH 

166 INTERBASE 5
UNDERSTANDING THE EVENT MECHANISM

Synchronous event notification

:KHQDQDSSOLFDWLRQGHSHQGVRQWKHRFFXUUHQFHRIDVSHFLILFHYHQWIRUSURFHVVLQJLWVKRXOG
XVHV\QFKURQRXVHYHQWQRWLILFDWLRQWRVXVSHQGLWVRZQH[HFXWLRQXQWLOWKHHYHQWRFFXUV)RU
H[DPSOHDQDXWRPDWHGVWRFNWUDGLQJDSSOLFDWLRQWKDWEX\VRUVHOOVVWRFNZKHQVSHFLILFSULFH
FKDQJHVRFFXUPLJKWVWDUWH[HFXWLRQVHWXS(3%VUHJLVWHULQWHUHVWLQDVHWRIVWRFNVWKHQ
VXVSHQGLWVRZQH[HFXWLRQXQWLOWKRVHSULFHFKDQJHVRFFXU
7KHisc_wait_for_event()IXQFWLRQSURYLGHVV\QFKURQRXVHYHQWKDQGOLQJIRUDQDSSOLFDWLRQ
)RUPRUHLQIRUPDWLRQDERXWV\QFKURQRXVHYHQWKDQGOLQJVHH´:DLWLQJRQHYHQWVZLWK
LVFBZDLWBIRUBHYHQW  µRQSDJH 

Asynchronous event notification

:KHQDQDSSOLFDWLRQQHHGVWRUHDFWWRSRVVLEOHGDWDEDVHHYHQWVEXWDOVRQHHGV
WRFRQWLQXHSURFHVVLQJZKHWKHURUQRWWKRVHHYHQWVRFFXULWVKRXOGVHWXSDQDV\QFKURQRXV
WUDS $67 IXQFWLRQDQGXVHDV\QFKURQRXVHYHQWQRWLILFDWLRQWRUHJLVWHULQWHUHVWLQHYHQWV
ZKLOHFRQWLQXLQJLWVRZQSURFHVVLQJ)RUH[DPSOHDVWRFNEURNHULQJDSSOLFDWLRQUHTXLUHV
FRQVWDQWDFFHVVWRDGDWDEDVHRIVWRFNVWRDOORZDEURNHUWREX\DQGVHOOVWRFNEXWDWWKHVDPH
WLPHPD\ZDQWWRXVHHYHQWVWRDOHUWWKHEURNHUWRSDUWLFXODUO\VLJQLILFDQWRUYRODWLOHVWRFN
SULFHFKDQJHV
7KHisc_que_events()IXQFWLRQDQGWKH$67IXQFWLRQSURYLGHDV\QFKURQRXVHYHQWKDQGOLQJ
IRUDQDSSOLFDWLRQ)RUPRUHLQIRUPDWLRQDERXWDV\QFKURQRXVHYHQWKDQGOLQJVHH
´&RQWLQXRXVSURFHVVLQJZLWKLVFBTXHBHYHQWV  µRQSDJH 

Transaction control of events

(YHQWVRFFXUXQGHUWUDQVDFWLRQFRQWURODQGFDQWKHUHIRUHEHFRPPLWWHGRUUROOHGEDFN
,QWHUHVWHGDSSOLFDWLRQVGRQRWUHFHLYHQRWLILFDWLRQRIDQHYHQWXQWLOWKHWUDQVDFWLRQIURP
ZKLFKWKHHYHQWLVSRVWHGLVFRPPLWWHG,IDSRVWHGHYHQWLVUROOHGEDFNQRWLILFDWLRQGRHVQRW
RFFXU
$WUDQVDFWLRQFDQSRVWWKHVDPHHYHQWPRUHWKDQRQFHEHIRUHFRPPLWWLQJEXWUHJDUGOHVVRI
KRZPDQ\WLPHVDQHYHQWLVSRVWHGLWLVUHJDUGHGDVDVLQJOHHYHQWRFFXUUHQFHIRUSXUSRVHV
RIHYHQWQRWLILFDWLRQ

API GUIDE 167

 CHAPTER 11 WORKING WITH EVENTS

Creating EPBs with isc_event_block( )

%HIRUHDQDSSOLFDWLRQFDQUHJLVWHULQWHUHVWLQDQHYHQWLWPXVWHVWDEOLVKDQGSRSXODWHWZR
HYHQWSDUDPHWHUEXIIHUV (3%V RQHIRUKROGLQJWKHLQLWLDORFFXUUHQFHFRXQWYDOXHVIRUHDFK
HYHQWRILQWHUHVWDQGDQRWKHUIRUKROGLQJWKHFKDQJHGRFFXUUHQFHFRXQWYDOXHV7KHVH
EXIIHUVDUHSDVVHGDVSDUDPHWHUVWRVHYHUDO$3,HYHQWIXQFWLRQV
,Q&HDFK(3%LVGHFODUHGDVDFKDUSRLQWHUDVIROORZV
char *event_buffer, *result_buffer;
2QFHWKHEXIIHUVDUHGHFODUHGisc_event_block()LVFDOOHGWRDOORFDWHVSDFHIRUWKHPDQGWR
SRSXODWHWKHPZLWKVWDUWLQJYDOXHV
isc_event_block()DOVRUHTXLUHVDWOHDVWWZRDGGLWLRQDOSDUDPHWHUVWKHQXPEHURIHYHQWVLQ
ZKLFKDQDSSOLFDWLRQLVUHJLVWHULQJLQWHUHVWDQGIRUHDFKHYHQWDVWULQJQDPLQJWKHHYHQW$
VLQJOHFDOOWRisc_event_block()FDQSDVVXSWRHYHQWQDPHVWULQJV(YHQWQDPHVPXVW
PDWFKWKHQDPHVRIHYHQWVSRVWHGE\VWRUHGSURFHGXUHVRUWULJJHUV
isc_event_block()DOORFDWHVWKHVDPHDPRXQWRIVSDFHIRUHDFK(3%HQRXJKWRKDQGOHHDFK
QDPHGHYHQW,WUHWXUQVDVLQJOHYDOXHLQGLFDWLQJWKHVL]HLQE\WHVRIHDFKEXIIHU
7KHV\QWD[IRUisc_event_block()LV
ISC_LONG isc_event_block(
char **event_buffer,
char **result_buffer,
unsigned short id_count,
. . . );
)RUH[DPSOHWKHIROORZLQJFRGHVHWVXS(3%VIRUWKUHHHYHQWV
#include <ibase.h>;
. . .
char *event_buffer, *result_buffer;
long blength;
. . .
blength = isc_event_block(&event_buffer, &result_buffer, 3, "BORL",
"INTEL", "SUN");
. . .

7KLVFRGHDVVXPHVWKDWWKHUHDUHWULJJHUVRUVWRUHGSURFHGXUHVGHILQHGIRUWKHGDWDEDVHWKDW
SRVWHYHQWVQDPHG´%25/µ´,17(/µDQG´681µ

7,3 $SSOLFDWLRQVWKDWQHHGWRUHVSRQGWRPRUHWKDQHYHQWVFDQPDNHPXOWLSOHFDOOVWR
isc_event_block()VSHFLI\LQJGLIIHUHQW(3%VDQGHYHQWOLVWVIRUHDFKFDOO
)RUWKHFRPSOHWHV\QWD[RIisc_event_block()VHH´LVFBHYHQWBEORFN µRQSDJH 

168 INTERBASE 5
WAITING ON EVENTS WITH ISC_WAIT_FOR_EVENT( )

Waiting on events with isc_wait_for_event( )

$IWHUVHWWLQJXS(3%VDQGVSHFLI\LQJHYHQWVRILQWHUHVWZLWKisc_event_block()DQ
DSSOLFDWLRQFDQXVHisc_wait_for_event()WRUHJLVWHULQWHUHVWLQWKRVHHYHQWVDQGSDXVHLWV
H[HFXWLRQXQWLORQHRIWKHHYHQWVRFFXUV

,03257$17 isc_wait_for_event()FDQQRWEHXVHGLQ0LFURVRIW:LQGRZVDSSOLFDWLRQVRUXQGHUDQ\
RWKHURSHUDWLQJV\VWHPWKDWGRHVQRWSHUPLWSURFHVVHVWRSDXVH$SSOLFDWLRQVRQWKHVH
SODWIRUPVPXVWXVHDV\QFKURQRXVHYHQWKDQGOLQJ
7KHV\QWD[IRUisc_wait_for_event()LV
ISC_STATUS isc_wait_for_event(
ISC_STATUS *status_vector,
isc_db_handle *db_handle,
short length,
char *event_buffer,
char *result_buffer);
)RUH[DPSOHWKHIROORZLQJFRGHVHWVXS(3%VIRUWKUHHHYHQWVWKHQFDOOV
isc_wait_for_event()WRVXVSHQGLWVH[HFXWLRQXQWLORQHRIWKHHYHQWVRFFXUV
#include <ibase.h>;
. . .
char *event_buffer, *result_buffer;
long blength;
ISC_STATUS status_vector[20];
isc_db_handle db1;
. . .
/* Assume database db1 is attached here and a transaction started. */
blength = isc_event_block(&event_buffer, &result_buffer, 3, "BORL",
"INTEL", "SUN");
isc_wait_for_event(status_vector, &db1, (short)blength,
event_buffer, result_buffer);
/* Application processing is suspended here until an event occurs. */
. . .
2QFHisc_wait_for_event()LVFDOOHGDSSOLFDWLRQSURFHVVLQJVWRSVXQWLORQHRIWKHUHTXHVWHG
HYHQWVLVSRVWHG:KHQWKHHYHQWRFFXUVDSSOLFDWLRQSURFHVVLQJUHVXPHVDWWKHQH[W
H[HFXWDEOHVWDWHPHQWIROORZLQJWKHFDOOWRisc_wait_for_event(),IDQDSSOLFDWLRQLVZDLWLQJ
RQPRUHWKDQRQHHYHQWLWPXVWXVHisc_event_counts()WRGHWHUPLQHZKLFKHYHQWZDV
SRVWHG
Note $VLQJOHFDOOWRisc_wait_for_event()FDQZDLWRQDPD[LPXPRIHYHQWV
$SSOLFDWLRQVWKDWQHHGWRZDLWRQPRUHWKDQHYHQWVPXVWZDLWRQRQHVHWRIWKHQPDNH
DQRWKHUFDOOWRisc_wait_for_event()WRZDLWRQDGGLWLRQDOHYHQWV

API GUIDE 169

 CHAPTER 11 WORKING WITH EVENTS

)RUWKHFRPSOHWHV\QWD[RIisc_wait_for_event()VHH´LVFBZDLWBIRUBHYHQW µRQSDJH 

Continuous processing with isc_que_events( )

isc_que_events()LVFDOOHGWRUHTXHVWDV\QFKURQRXVQRWLILFDWLRQRIHYHQWVOLVWHGLQDQHYHQW
EXIIHUSDVVHGDVDQDUJXPHQW8SRQFRPSOHWLRQRIWKHFDOOEXWEHIRUHDQ\HYHQWVDUHSRVWHG
FRQWUROLVUHWXUQHGWRWKHFDOOLQJDSSOLFDWLRQVRWKDWLWFDQFRQWLQXHSURFHVVLQJ
:KHQDUHTXHVWHGHYHQWLVSRVWHG,QWHU%DVHFDOOVDQDV\QFKURQRXVWUDS $67 IXQFWLRQDOVR
SDVVHGDVDSDUDPHWHUWRisc_que_events()WRKDQGOHWKHSRVWLQJ7KH$67LVDIXQFWLRQRU
VXEURXWLQHLQWKHFDOOLQJDSSOLFDWLRQWKHVROHSXUSRVHRIZKLFKLVWRSURFHVVWKHHYHQWSRVWLQJ
IRUWKHDSSOLFDWLRQ
7KHV\QWD[IRUisc_que_events()LV
ISC_STATUS isc_que_events(
ISC_STATUS *status_vector,
isc_db_handle *db_handle,
ISC_LONG *event_id,
short length,
char *event_buffer,
isc_callback event_function,
void *event_function_arg);

HYHQWBLGLVDORQJSRLQWHUWKDWLVXVHGDVDKDQGOHLQVXEVHTXHQWFDOOVWRisc_cancel_events()
WRWHUPLQDWHHYHQWQRWLILFDWLRQ,WQHHGQRWEHLQLWLDOL]HGZKHQSDVVHG7KHOHQJWKSDUDPHWHU
LVWKHVL]HRIHYHQWBEXIIHUZKLFKFRQWDLQVWKHFXUUHQWFRXQWRIHYHQWVWREHZDLWHGXSRQ
HYHQWBIXQFWLRQLVDSRLQWHUWRWKH$67IXQFWLRQWKDW,QWHU%DVHVKRXOGFDOOZKHQDQHYHQWRI
LQWHUHVWLVSRVWHG,WLVXSWRWKH$67IXQFWLRQWRQRWLI\WKHDSSOLFDWLRQWKDWLWKDVEHHQFDOOHG
SHUKDSVE\VHWWLQJDJOREDOIODJRIVRPHNLQGHYHQWBIXQFWLRQBDUJLVDSRLQWHUWRWKHILUVW
SDUDPHWHUWRSDVVWRWKH$67
)RUDFRPSOHWHH[DPSOHRIDFDOOWRisc_que_events()DQGDFDOOWRDQ$67VHH´$FRPSOHWH
LVFBTXHBHYHQWV  H[DPSOHµRQSDJH 

Creating an AST
7KHHYHQWIXQFWLRQHYHQWBIXQFWLRQVKRXOGEHZULWWHQWRWDNHWKUHHDUJXPHQWV

170 INTERBASE 5
CONTINUOUS PROCESSING WITH ISC_QUE_EVENTS( )

 7KHHYHQWBIXQFWLRQBDUJVSHFLILHGLQWKHFDOOWRisc_que_events()7KLVLVXVXDOO\D
SRLQWHUWRWKHHYHQWSDUDPHWHUEXIIHUWKDWVKRXOGEHILOOHGLQZLWKXSGDWHGHYHQW
FRXQWV
 7KHOHQJWKRIWKHIROORZLQJHYHQWVBOLVWEXIIHU
 $SRLQWHUWRWKHHYHQWVBOLVWEXIIHUDWHPSRUDU\HYHQWSDUDPHWHUEXIIHUMXVWOLNH
WKDWSDVVHGWRisc_que_events()H[FHSWIRUKDYLQJXSGDWHGHYHQWFRXQWV
$UHVXOWEXIIHULVQRWDXWRPDWLFDOO\XSGDWHGE\WKHHYHQWRFFXUUHQFHLWLVXSWRWKH
HYHQWBIXQFWLRQWRFRS\WKHWHPSRUDU\HYHQWVBOLVWEXIIHUWRWKHPRUHSHUPDQHQWEXIIHUWKDWWKH
DSSOLFDWLRQXWLOL]HV
HYHQWBIXQFWLRQDOVRQHHGVWROHWWKHDSSOLFDWLRQNQRZWKDWLWKDVEHHQFDOOHGIRUH[DPSOHE\
VHWWLQJDJOREDOIODJ
$VDPSOHHYHQWBIXQFWLRQDSSHDUVLQWKHIROORZLQJH[DPSOH
isc_callback event_function
(char *result, short length, char *updated)
{
/* Set the global event flag. */
event_flag++
/* Copy the temporary updated buffer to the result buffer. */
while (length--)
*result++ = *updated++;
return(0);
};

A complete isc_que_events( ) example

7KHIROORZLQJSURJUDPIUDJPHQWLOOXVWUDWHVFDOOLQJisc_que_events()WRZDLWDV\QFKURQRXVO\
IRUHYHQWRFFXUUHQFHV:LWKLQDORRSLWSHUIRUPVRWKHUSURFHVVLQJDQGFKHFNVWKHHYHQWIODJ
SUHVXPDEO\VHWE\WKHVSHFLILHGHYHQWIXQFWLRQ WRGHWHUPLQHZKHQDQHYHQWKDVEHHQSRVWHG
,IRQHKDVWKHSURJUDPUHVHWVWKHHYHQWIODJFDOOVisc_event_counts()WRGHWHUPLQHZKLFK
HYHQWVKDYHEHHQSRVWHGVLQFHWKHODVWFDOOWRisc_que_events()DQGFDOOVisc_que_events()
WRLQLWLDWHDQRWKHUDV\QFKURQRXVZDLW
#include <ibase.h>
#define number_of_stocks 3;
#define MAX_LOOP 10
char *event_names[] = {"DEC", "HP", "SUN"};
char *event_buffer, *result_buffer;
ISC_STATUS status_vector[20];
short length;

API GUIDE 171

 CHAPTER 11 WORKING WITH EVENTS

ISC_LONG event_id;
int i, counter;
int event_flag = 0;
length = (short)isc_event_block(
&event_buffer,
&result_buffer,
number_of_stocks,
"DEC", "HP", "SUN");
isc_que_events(
status_vector,
&database_handle, /* Set in previous isc_attach_database(). */
&event_id,
length, /* Returned from isc_event_block(). */
event_buffer,
(isc_callback)event_function,
result_buffer);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector); /* Display error message. */
return(1);
};
counter = 0;
while (counter < MAX_LOOP)
{
counter++;
if (!event_flag)
{
/* Do whatever other processing you want. */
;
}
else
{ event_flag = 0;
isc_event_counts(
status_vector,
length,
event_buffer,
result_buffer);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector); /* Display error message. */
return(1);
};
for (i=0; i<number_of_stocks; i++)
if (status_vector[i])

172 INTERBASE 5
DETERMINING WHICH EVENTS OCCURRED WITH ISC_EVENT_COUNTS( )

{
/* The event has been posted. Do whatever is appropriate,
e.g., initiating a buy or sell order.
Note: event_names[i] tells the name of the event
corresponding to status_vector[i]. */
;
}
isc_que_events(
status_vector,
&database_handle,
&event_id,
length,
event_buffer,
(isc_callback)event_function,
result_buffer);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector); /* Display error message. */
return(1);
}
} /* End of else. */
} /* End of while. */
/* Let InterBase know you no longer want to wait asynchronously. */
isc_cancel_events(
status_vector,
&database_handle,
&event_id);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector); /* Display error message. */
return(1);
}

Determining which events occurred with isc_event_counts( )

:KHQDQDSSOLFDWLRQUHJLVWHUVLQWHUHVWLQPXOWLSOHHYHQWVDQGUHFHLYHVQRWLILFDWLRQWKDWDQ
HYHQWRFFXUUHGWKHDSSOLFDWLRQPXVWXVHisc_event_counts()WRGHWHUPLQHZKLFKHYHQWRU
HYHQWVRFFXUUHGisc_event_counts()VXEWUDFWVYDOXHVLQWKHHYHQWBEXIIHUDUUD\IURPWKHYDOXHV
LQWKHUHVXOWBEXIIHUDUUD\WRGHWHUPLQHWKHQXPEHURIWLPHVHDFKHYHQWKDVRFFXUUHGVLQFHDQ
DSSOLFDWLRQUHJLVWHUHGLQWHUHVWLQDVHWRIHYHQWVHYHQWBEXIIHUDQGUHVXOWBEXIIHUDUHYDULDEOHV
GHFODUHGZLWKLQDQDSSOLFDWLRQDQGDOORFDWHGDQGLQLWLDOL]HGE\isc_event_block()

API GUIDE 173

 CHAPTER 11 WORKING WITH EVENTS

7KHGLIIHUHQFHRIHDFKHOHPHQWLVUHWXUQHGLQWKHHUURUVWDWXVDUUD\WKDWLVSDVVHGWR
isc_event_counts()7RGHWHUPLQHZKLFKHYHQWVRFFXUUHGDQDSSOLFDWLRQPXVWH[DPLQH
HDFKHOHPHQWRIWKHDUUD\IRUQRQ]HURYDOXHV$QRQ]HURFRXQWLQGLFDWHVWKHQXPEHURIWLPHV
DQHYHQWLVSRVWHGEHWZHHQWKHWLPHisc_event_block()LVFDOOHGDQGWKHILUVWWLPHDQHYHQW
LVSRVWHGDIWHUisc_wait_for_event()RUisc_que_events()DUHFDOOHG:KHUHPXOWLSOH
DSSOLFDWLRQVDUHDFFHVVLQJWKHVDPHGDWDEDVHWKHUHIRUHDSDUWLFXODUHYHQWFRXQWPD\EHRU
PRUHDQGPRUHWKDQRQHHYHQWFRXQWHOHPHQWPD\EHQRQ]HUR
Note :KHQILUVWVHWWLQJXSDQ$67WRWUDSHYHQWVZLWKisc_que_events(),QWHU%DVH
LQLWLDOL]HVDOOFRXQWYDOXHVLQWKHVWDWXVYHFWRUWRUDWKHUWKDQ7RFOHDUWKHYDOXHVFDOO
isc_event_counts()WRUHVHWWKHYDOXHV
,QDGGLWLRQWRGHWHUPLQLQJZKLFKHYHQWRFFXUUHGisc_event_counts()UHLQLWLDOL]HVWKH
HYHQWBEXIIHUDUUD\LQDQWLFLSDWLRQRIDQRWKHUFDOOWRisc_wait_for_event()RU
isc_que_events()9DOXHVLQHYHQWBEXIIHUDUHVHWWRWKHVDPHYDOXHVDVFRUUHVSRQGLQJYDOXHVLQ
UHVXOWBEXIIHU
7KHFRPSOHWHV\QWD[IRUisc_event_counts()LV
void isc_event_counts(
ISC_STATUS status_vector,
short buffer_length,
char *event_buffer,
char *result_buffer);
)RUH[DPSOHWKHIROORZLQJFRGHGHFODUHVLQWHUHVWLQWKUHHHYHQWVZDLWVRQWKHPWKHQXVHV
isc_event_counts()WRGHWHUPLQHZKLFKHYHQWVRFFXUUHG
#include <ibase.h>;
. . .
char *event_buffer, *result_buffer;
long blength;
ISC_STATUS status_vector[20];
isc_db_handle db1;
long count_array[3];
int i;
. . .
/* Assume database db1 is attached here and a transaction started. */
blength = isc_event_block(&event_buffer, &result_buffer, 3, "BORL",
"INTEL", "SUN");
isc_wait_for_event(status_vector, &db1, (short)blength,
event_buffer, result_buffer);
/* Application processing is suspended here until an event occurs. */
isc_event_counts(status_vector, (short)blength, event_buffer,
result_buffer);
for (i = 0; i < 3; i++)
{

174 INTERBASE 5
CANCELING INTEREST IN ASYNCHRONOUS EVENTS WITH ISC_CANCEL_EVENTS( )

if (status_vector[i])
{
/* Process the event here. */
;
}
}

)RUPRUHLQIRUPDWLRQDERXWisc_event_counts()VHH´LVFBHYHQWBFRXQWV µRQSDJH RI

&KDSWHU´$3,)XQFWLRQ5HIHUHQFHµ

Canceling interest in asynchronous events

with isc_cancel_events( )
$QDSSOLFDWLRQWKDWUHTXHVWHGDV\QFKURQRXVHYHQWQRWLILFDWLRQZLWKisc_que_events()FDQ
VXEVHTXHQWO\FDQFHOWKHQRWLILFDWLRQUHTXHVWDWDQ\WLPHZLWKisc_cancel_events()XVLQJWKH
IROORZLQJV\QWD[
ISC_STATUS isc_cancel_events(
ISC_STATUS *status_vector,
isc_db_handle *db_handle,
ISC_LONG *event_id);
HYHQWBLGLVDQHYHQWKDQGOHVHWLQDSUHYLRXVFDOOWRisc_que_events())RUH[DPSOHWKH
IROORZLQJFRGHFDQFHOVLQWHUHVWLQWKHHYHQWRUHYHQWVLGHQWLILHGE\HYHQWBLG
include <ibase.h>;
. . .
/* For example code leading up to this call, see the code example
in "Continuous Processing with isc_event_que(), earlier in this
chapter. */
isc_cancel_events(status_vector, &db_handle, &event_id);

API GUIDE 175

 PART II

API PartII

Reference
Guide
3DUW,,$3,5HIHUHQFH*XLGH
 CHAPTER

API Function Reference

Chapter12
12
7KLVFKDSWHULVDQDOSKDEHWLFDOUHIHUHQFHIRUWKH,QWHU%DVH$3,IXQFWLRQFDOOV,WSURYLGHV
WDEOHVWKDWFDWHJRUL]HFDOOVE\WKHWDVNVWKH\SHUIRUPDQGWKHQSURYLGHVDQDOSKDEHWLFDODQG
GHWDLOHGGHVFULSWLRQRIHDFKFDOOLQFOXGLQJLWVV\QWD[DUJXPHQWVH[DPSOHVRIXVHDQGFURVV
UHIHUHQFHVWRUHODWHGFDOOV

Function categories
7KHUHDUHWHQFODVVHVRI,QWHU%DVH$3,IXQFWLRQFDOOV
g $UUD\IXQFWLRQVIRUKDQGOLQJDUUD\VRIGDWD
g %OREIXQFWLRQVIRUKDQGOLQJWKH,QWHU%DVH%OREGDWDW\SH
g 'DWDEDVHIXQFWLRQVIRUKDQGOLQJGDWDEDVHUHTXHVWV
g &RQYHUVLRQIXQFWLRQVIRUWUDQVODWLQJGDWHVEHWZHHQ,QWHU%DVHIRUPDWDQG8QL[WPIRUPDW
DQGIRUUHYHUVLQJWKHE\WHRUGHURILQWHJHUV
g '64/IXQFWLRQVIRUKDQGOLQJ64/VWDWHPHQWVHQWHUHGE\XVHUVDWUXQWLPH
g (UURUKDQGOLQJIXQFWLRQV
g (YHQWIXQFWLRQVIRUUHJLVWHULQJLQWHUHVWLQHYHQWVSRVWHGE\WULJJHUVDQGVWRUHGSURFHGXUHVLQ
DSSOLFDWLRQVDQGIRUSURFHVVLQJWKHHYHQWTXHXH

179
 CHAPTER 12 API FUNCTION REFERENCE

g ,QIRUPDWLRQIXQFWLRQVIRUUHWULHYLQJLQIRUPDWLRQDERXWGDWDEDVHVWUDQVDFWLRQV%OREGDWD
DQGHYHQWV
g 6HFXULW\IXQFWLRQVIRUDGGLQJGHOHWLQJDQGPRGLI\LQJXVHUUHFRUGVLQWKHSDVVZRUGGDWDEDVH
g 7UDQVDFWLRQIXQFWLRQVIRUKDQGOLQJWUDQVDFWLRQVLQDQDSSOLFDWLRQ
6RPHIXQFWLRQVVXFKDVLQIRUPDWLRQFDOOVRFFXULQPRUHWKDQRQHFODVV

Array functions
7KHIROORZLQJWDEOHVXPPDUL]HVWKH,QWHU%DVH$3,IXQFWLRQVDYDLODEOHIRUKDQGOLQJDUUD\GDWD
LQDQDSSOLFDWLRQ

Function name Purpose

isc_array_get_slice() Retrieve a specified part of an array field
isc_array_lookup_bounds() Determine the dimensions of an array field
isc_array_lookup_desc() Retrieve an array description
isc_array_put_slice() Write a specified part of an array field
isc_array_set_desc() Set an array description
TABLE 12.1 Array functions

Blob functions
7KHIROORZLQJWDEOHVXPPDUL]HVWKH,QWHU%DVH$3,IXQFWLRQVDYDLODEOHIRUKDQGOLQJ%OREGDWD
LQDQDSSOLFDWLRQ

Function name Purpose

isc_blob_default_desc() Set a default Blob description for dynamic access
isc_blob_gen_bpb() Generate a Blob parameter buffer (BPB) for dynamic access
isc_blob_info() Request information about a Blob field
isc_blob_lookup_desc() Retrieve a Blob description
isc_blob_set_desc() Set a Blob description
TABLE 12.2 Blob functions

180 INTERBASE 5
FUNCTION CATEGORIES

Function name Purpose

isc_cancel_blob() Discard a Blob
isc_close_blob() Close a Blob
isc_create_blob2() Create a new Blob
isc_get_segment() Retrieve a segment of Blob data
isc_open_blob2() Open a Blob for read access
isc_put_segment() Write a segment of Blob data
TABLE 12.2 Blob functions (continued)

Database functions
7KHIROORZLQJWDEOHVXPPDUL]HVWKH,QWHU%DVH$3,IXQFWLRQVDYDLODEOHIRUKDQGOLQJGDWDEDVH
UHTXHVWVLQDQDSSOLFDWLRQ

Function name Purpose

isc_attach_database() Connect to an existing database
isc_database_info() Request information about an attached database
isc_detach_database() Disconnect from a database
isc_drop_database() Delete an attached database and its associated files
isc_expand_dpb() Build a database parameter buffer (DPB) dynamically
isc_version() Retrieve database implementation number and on-disk
structure (ODS) major and minor version numbers
TABLE 12.3 Database functions

API GUIDE 181

 CHAPTER 12 API FUNCTION REFERENCE

Conversion functions
7KHIROORZLQJWDEOHVXPPDUL]HVWKH,QWHU%DVH$3,IXQFWLRQVDYDLODEOHIRUWUDQVODWLQJ
EHWZHHQ,QWHU%DVH'$7(IRUPDWDQGWKH8QL[WPGDWHIRUPDWDQGIRUUHYHUVLQJWKH
E\WHRUGHURIDQLQWHJHU

Function name Purpose

isc_decode_date() Translate a date from InterBase format to C tm format
isc_encode_date() Translate a date from C tm format to InterBase format
isc_vax_integer() Reverse the byte-order of an integer
TABLE 12.4 Date and conversion functions

DSQL functions
7KHIROORZLQJWDEOHVXPPDUL]HVWKH,QWHU%DVH$3,IXQFWLRQVDYDLODEOHIRUKDQGOLQJ'64/
VWDWHPHQWVEXLOWRUHQWHUHGE\XVHUVDWUXQWLPH

Function name Purpose

isc_dsql_allocate_statement() Allocate a statement handle
isc_dsql_alloc_statement2() Allocate a statement handle that is automatically freed on database
detachment
isc_dsql_describe() Fill in an XSQLDA with information about values returned by a
statement
isc_dsql_describe_bind() Fill in an XSQLDA with information about a statement’s input
parameters
isc_dsql_execute() Execute a prepared statement
isc_dsql_execute2() Execute a prepared statement returning a single set of values
isc_dsql_execute_immediate() Prepare and execute a statement without return values for
one-time use
isc_dsql_exec_immed2() Prepare and execute a statement with a single set of return values
for one-time use
TABLE 12.5 DSQL functions

182 INTERBASE 5
FUNCTION CATEGORIES

Function name Purpose

isc_dsql_fetch() Retrieve data returned by a previously prepared and executed
statement
isc_dsql_free_statement() Free a statement handle, or close a cursor associated with a
statement handle
isc_dsql_prepare() Prepare a statement for execution
isc_dsql_set_cursor_name() Define a cursor name and associate it with a statement handle
isc_dsql_sql_info() Request information about a prepared statement
TABLE 12.5 DSQL functions (continued)

Error-handling functions
7KHIROORZLQJWDEOHVXPPDUL]HVWKH,QWHU%DVH$3,IXQFWLRQVDYDLODEOHIRUKDQGOLQJGDWDEDVH
HUURUFRQGLWLRQVDQDSSOLFDWLRQ

Function name Purpose

isc_interprete() Capture InterBase error messages to a buffer
isc_print_sqlerror() Display an SQL error message
isc_print_status() Display InterBase error messages
isc_sqlcode() Set the value of SQLCODE
isc_sql_interprete() Capture an SQL error message to a buffer
TABLE 12.6 Error-handling functions

API GUIDE 183

 CHAPTER 12 API FUNCTION REFERENCE

Event functions
7KHIROORZLQJWDEOHVXPPDUL]HVWKH,QWHU%DVH$3,IXQFWLRQVDYDLODEOHIRUKDQGOLQJHYHQWVLQ
DQDSSOLFDWLRQ

Function name Purpose

isc_cancel_events() Cancel interest in an event
isc_event_block() Allocate event parameter buffers
isc_event_counts() Get the change in values of event counters in the event array
isc_que_events() Wait asynchronously until an event is posted
isc_wait_for_event() Wait synchronously until an event is posted
TABLE 12.7 Event functions

Information functions
7KHIROORZLQJWDEOHVXPPDUL]HVWKH,QWHU%DVH$3,IXQFWLRQVDYDLODEOHIRUUHSRUWLQJ
LQIRUPDWLRQDERXWGDWDEDVHVWUDQVDFWLRQVDQG%OREGDWDWRDFOLHQWDSSOLFDWLRQWKDWUHTXHVWV
LW

Function name Purpose

isc_blob_info() Request information about a Blob field
isc_database_info() Request information about an attached database
isc_dsql_sql_info() Request information about a prepared DSQL statement
isc_transaction_info() Request information about a specified transaction
isc_version() Retrieve database implementation number and on-disk structure (ODS)
major and minor version numbers
TABLE 12.8 Information functions

184 INTERBASE 5
FUNCTION CATEGORIES

Security functions
7KHIROORZLQJWDEOHVXPPDUL]HVWKH,QWHU%DVH$3,IXQFWLRQVDYDLODEOHIRUDGGLQJGHOHWLQJ
DQGPRGLI\LQJXVHUUHFRUGVLQWKHSDVVZRUGGDWDEDVH

Function name Purpose

isc_add_user() Adds a user to the password database
isc_delete_user() Deletes a user from the password database
isc_modify_user() Modifies user information in the password database
TABLE 12.9 Security functions

Transaction control functions

7KHIROORZLQJWDEOHVXPPDUL]HVWKH,QWHU%DVH$3,IXQFWLRQVDYDLODEOHIRUFRQWUROOLQJ
WUDQVDFWLRQVLQDQDSSOLFDWLRQ

Function name Purpose

isc_commit_retaining() Commit a transaction, and start a new one using the original
transaction’s context
isc_commit_transaction() Save a transaction’s database changes, and end the transaction
isc_prepare_transaction() Execute the first phase of a two-phase commit
isc_prepare_transaction2() Execute the second phase of a two-phase commit
isc_rollback_transaction() Undo a transaction’s database changes, and end the transaction
isc_start_multiple() Begin new transactions (used on systems that do not support a
variable number of input arguments)
isc_start_transaction() Begin new transactions
isc_transaction_info() Request information about a specified transaction
TABLE 12.10 Transaction control functions

API GUIDE 185

 CHAPTER 12 API FUNCTION REFERENCE

Using function definitions

(DFKIXQFWLRQGHILQLWLRQLQWKLVFKDSWHULQFOXGHVWKHHOHPHQWVLQWKHIROORZLQJWDEOH

Element Description
Title Function name
Definition Main purpose of function
Syntax Diagram of the function and parameters
Parameters Table describing each parameter
Description Detailed information about using the function
Example Example of using the function in a program
Return value Description of possible values returned in the status vector, if any
See also Cross references to other related functions
TABLE 12.11 Function description format

186 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_add_user( )
$GGVDXVHUUHFRUGWRWKHSDVVZRUGGDWDEDVHLVFJGE

6\QWD[ ISC_STATUS isc_add_user(

ISC_STATUS *status
USER_SEC_DATA *user_sec_data);

Parameter Type Description

status vector ISC_STATUS * Pointer to the error status vector
user_sec_data USER_SEC_DATA * Pointer to a struct that is defined in ibase.h

'HVFULSWLRQ 7KHWKUHHVHFXULW\IXQFWLRQVisc_add_user()isc_delete_user()DQGisc_modify_user()
PLUURUIXQFWLRQDOLW\WKDWLVDYDLODEOHLQWKHgsecFRPPDQGOLQHXWLOLW\isc_add_user()DGGV
DUHFRUGWRLVFJGE,QWHU%DVH·VSDVVZRUGGDWDEDVH
$WDPLQLPXP\RXPXVWSURYLGHWKHXVHUQDPHDQGSDVVZRUG,IWKHVHUYHULVQRWORFDO\RX
PXVWDOVRSURYLGHDVHUYHUQDPHDQGSURWRFRO9DOLGFKRLFHVIRUWKHSURWRFROILHOGDUH
VHFBSURWRFROBWFSLSVHFBSURWRFROBQHWEHXLVHFBSURWRFROBVS[DQGVHFBSURWRFROBORFDO
,QWHU%DVHUHDGVWKHVHWWLQJVIRUWKH,6&B86(5DQG,6&B3$66:25'HQYLURQPHQWYDULDEOHVLI
\RXGRQRWSURYLGHD'%$XVHUQDPHDQGSDVVZRUG
7KHGHILQLWLRQIRUWKH86(5B6(&B'$7$VWUXFWLQLEDVHKLVDVIROORZV
typedef struct {
short sec_flags; /* which fields are specified */
int uid; /* the user’s id */
int gid; /* the user’s group id */
int protocol; /* protocol to use for connection */
char *server; /* server to administer */
char *user_name; /* the user’s name */
char *password; /* the user’s password */
char *group_name; /* the group name */
char *first_name; /* the user’s first name */
char *middle_name; /* the user’s middle name */
char *last_name; /* the user’s last name */
char *dba_user_name; /* the dba user name */
char *dba_password; /* the dba password */
} USER_SEC_DATA;

API GUIDE 187

 CHAPTER 12 API FUNCTION REFERENCE

:KHQ\RXSDVVWKLVVWUXFWWRRQHRIWKHWKUHHVHFXULW\IXQFWLRQV\RXFDQWHOOLWZKLFKILHOGV
\RXKDYHVSHFLILHGE\GRLQJDELWZLVH25RIWKHIROORZLQJYDOXHVZKLFKDUHGHILQHGLQLEDVHK
sec_uid_spec 0x01
sec_gid_spec 0x02
sec_server_spec 0x04
sec_password_spec 0x08
sec_group_name_spec 0x10
sec_first_name_spec 0x20
sec_middle_name_spec 0x40
sec_last_name_spec 0x80
sec_dba_user_name_spec 0x100
sec_dba_password_spec 0x200

1RELWYDOXHVDUHDYDLODEOHIRUXVHUQDPHDQGSDVVZRUGVLQFHWKH\DUHUHTXLUHG
7KHIROORZLQJHUURUPHVVDJHVH[LVWIRUWKLVIXQFWLRQ

Code Value Description

isc_usrname_too_long 335544747 The user name passed in is greater than 31 bytes
isc_password_too_long 335544748 The password passed in is longer than 8 bytes
isc_usrname_required 335544749 The operation requires a user name
isc_password_required 335544750 The operation requires a password
isc_bad_protocol 335544751 The protocol specified is invalid
isc_dup_usrname_found 335544752 The user name being added already exists in the security
database
isc_usrname_not_found 335544753 The user name was not found in the security database
isc_error_adding_sec_record 335544754 An unknown error occurred while adding a user
isc_error_deleting_sec_record 335544755 An unknown error occurred while deleting a user
isc_error_modifying_sec_record 335544756 An unknown error occurred while modifying a user
isc_error_updating_sec_db 335544757 An unknown error occurred while updating the security
database
TABLE 12.12 Error messages for user security functions

188 INTERBASE 5
USING FUNCTION DEFINITIONS

([DPSOH 7KHIROORZLQJH[DPSOHDGGVDXVHU ´6RFNVµ WRWKHSDVVZRUGGDWDEDVHXVLQJWKHELWZLVH

25WHFKQLTXHIRUSDVVLQJYDOXHVIURPWKH86(5B6(&B'$7$VWUXFW
{
ISC_STATUS status[20];
USER_SEC_DATA sec;

sec.server = "kennel";
sec.dba_user_name = "sysdba";
sec.dba_password = "masterkey";
sec.protocol = sec_protocol_tcpip;
sec.first_name = "Socks";
sec.last_name = "Clinton";
sec.user_name = "socks";
sec.password = "2meow!"; /* Note: do not hardcode passwords */
sec.sec_flags = sec_server_spec
| sec_password_spec
| sec_dba_user_name_spec
| sec_dba_password_spec
| sec_first_name_spec
| sec_last_name_spec;
isc_add_user(status, &sec);
/* check status for errors */
if (status[0] == 1 && status[1])
{
switch (status[1]) {
case isc_usrname_too_long:
printf("Security database cannot accept long user names\n");
break;
...
}
}
}

5HWXUQ9DOXH isc_add_user()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHVVXFFHVV$
QRQ]HURYDOXHLQGLFDWHVDQHUURU6HHWKH´'HVFULSWLRQµVHFWLRQIRUWKLVIXQFWLRQIRUDOLVWRI
HUURUFRGHV)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU
´+DQGOLQJ(UURU&RQGLWLRQVµ

6HH$OVR isc_delete_user()isc_modify_user()

API GUIDE 189

 CHAPTER 12 API FUNCTION REFERENCE

isc_array_get_slice()
5HWULHYHVGDWDIURPDQDUUD\FROXPQLQDURZUHWXUQHGE\D6(/(&7

6\QWD[ ISC_STATUS isc_array_get_slice(

ISC_STATUS *status_vector,
isc_db_handle *db_handle,
isc_tr_handle *trans_handle,
ISC_QUAD *array_id,
ISC_ARRAY_DESC *desc,
void *dest_array,
ISC_LONG *slice_length);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
db_handle isc_db_handle * Pointer to a database handle set by a previous call to
isc_attach_database(); the handle identifies the
database containing the array column
db_handle returns an error in status_vector if it is NULL
trans_handle isc_tr_handle * Pointer to a transaction handle whose value has been set
by a previous isc_start_transaction() call;
trans_handle returns an error if NULL
array_id ISC_QUAD * Internal identifier for the array; the array ID must be
previously retrieved through API DSQL functions
desc ISC_ARRAY_DESC * Descriptor defining the array slice (entire array or subset)
to be retrieved
dest_array void * Pointer to a buffer of length slice_length into which the
array slice will be copied by this function
slice_length ISC_LONG * Length, in bytes, of the dest_array buffer

isc_array_get_slice()UHWULHYHVGDWDIURPDQDUUD\FROXPQRIDWDEOHURZXVLQJDQDUUD\,'
<RXFDQHLWKHUUHWULHYHDOOWKHDUUD\HOHPHQWVLQWKDWFROXPQRUDVXEVHWRIFRQWLJXRXVDUUD\
HOHPHQWVFDOOHGDVOLFH7KHXSSHUDQGORZHUERXQGDULHVLQWKHGHVFVWUXFWXUHVSHFLI\ZKLFK
HOHPHQWVDUHWREHUHWULHYHG

190 INTERBASE 5
USING FUNCTION DEFINITIONS

,QWHU%DVHFRSLHVWKHHOHPHQWVLQWRWKHEXIIHUGHVWBDUUD\ZKRVHVL]HLVVSHFLILHGE\VOLFHBOHQJWK
7KLVVKRXOGEHDWOHDVWWKHH[SHFWHGOHQJWKUHTXLUHGIRUWKHHOHPHQWVUHWULHYHG%HIRUH
UHWXUQLQJIURPisc_array_get_slice(),QWHU%DVHVHWVVOLFHBOHQJWKWRWKHDFWXDOQXPEHURI
E\WHVFRSLHG
%HIRUHFDOOLQJisc_array_get_slice()WKHUHDUHPDQ\RSHUDWLRQV\RXPXVWGRLQRUGHUWRILOO
LQWKHDUUD\GHVFULSWRUGHVFGHWHUPLQHWKHDSSURSULDWHLQWHUQDODUUD\LGHQWLILHUDUUD\BLGDQG
IHWFKWKHURZVZKRVHDUUD\FROXPQV\RXZDQWWRDFFHVV)RUFRPSOHWHVWHSE\VWHS
LQVWUXFWLRQVIRUVHWWLQJXSDQDUUD\GHVFULSWRUDQGUHWULHYLQJDUUD\LQIRUPDWLRQVHH&KDSWHU
´:RUNLQJZLWK$UUD\'DWDµ
Note 1HYHUH[HFXWHD'64/VWDWHPHQWWKDWWULHVWRDFFHVVDUUD\FROXPQGDWDGLUHFWO\XQOHVV
\RXDUHIHWFKLQJRQO\DVLQJOHHOHPHQW7KHZD\WRDFFHVVVOLFHVRIDUUD\FROXPQGDWDLVWRFDOO
isc_array_get_slice()RUisc_array_put_slice()7KHRQO\VXSSRUWHGDUUD\UHIHUHQFHVLQ
'64/VWDWHPHQWVDUHRQHVWKDWVSHFLI\DQHQWLUHDUUD\FROXPQ WKDWLVMXVWWKHFROXPQQDPH 
LQRUGHUWRJHWWKHLQWHUQDOLGHQWLILHUIRUWKHDUUD\ZKLFKLVUHTXLUHGE\isc_array_get_slice()
DQGisc_array_put_slice()RUVLQJOHHOHPHQWUHIHUHQFHV

([DPSOH 7KHIROORZLQJSURJUDPRSHUDWHVRQDWDEOHQDPHG352-B'(37B%8'*(7
7KLVWDEOHFRQWDLQVWKHTXDUWHUO\KHDGFRXQWVDOORFDWHGIRUHDFKSURMHFWLQHDFKGHSDUWPHQW
RIDQRUJDQL]DWLRQ(DFKURZRIWKHWDEOHDSSOLHVWRDSDUWLFXODUGHSDUWPHQWDQGSURMHFW
7KHTXDUWHUO\KHDGFRXQWVDUHFRQWDLQHGLQDQDUUD\FROXPQQDPHG
48$57(5/<B+($'B&17(DFKURZKDVIRXUHOHPHQWVLQWKLVFROXPQRQHSHUTXDUWHU
(DFKHOHPHQWRIWKHDUUD\LVDQXPEHURIW\SHORQJ
7KHH[DPSOHEHORZVHOHFWVWKHURZVFRQWDLQLQJLQIRUPDWLRQIRUWKHSURMHFWQDPHG
9%$6()RUHDFKVXFKURZLWUHWULHYHVDQGSULQWVWKHGHSDUWPHQWQXPEHUDQGWKHGDWDLQWKH
DUUD\FROXPQ WKDWLVWKHTXDUWHUO\KHDGFRXQWV 
,QDGGLWLRQWRLOOXVWUDWLQJWKHXVDJHRIisc_array_lookup_bounds()DQG
isc_array_get_slice()WKHSURJUDPVKRZVGDWDVWUXFWXUHLQLWLDOL]DWLRQVDQGFDOOVWRWKH
'64/IXQFWLRQVUHTXLUHGWRSUHSDUHDQGH[HFXWHWKH6(/(&7VWDWHPHQWWRREWDLQWKH
DUUD\BLGQHHGHGE\isc_array_get_slice()DQGWRIHWFKWKHVHOHFWHGURZVRQHE\RQH
#include <ibase.h>
#define Return_if_Error(stat) if (stat[0] == 1 && stat[1]) \
{ \
isc_print_status(stat); \
return(1); \
}
char *sel_str =
"SELECT dept_no, quarterly_head_cnt FROM proj_dept_budget \
WHERE year = 1994 AND proj_id = ’VBASE’";
char dept_no[6];
long hcnt[4], tr_handle, database_handle, SQLCODE;

API GUIDE 191

 CHAPTER 12 API FUNCTION REFERENCE

short len, i, flag0, flag1;

ISC_QUAD array_id;
ISC_ARRAY_DESC desc;
ISC_STATUS status_vector[20], fetch_stat;
isc_stmt_handle stmt = NULL;
XSQLDA *osqlda;
tr_handle = database_handle = 0L;
/* Attach to a database here--this code omitted for brevity */
/* Start a transaction here--this code omitted for brevity */
/* Set up the SELECT statement. */
/* Allocate the output XSQLDA for holding the array data. */
osqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(2));
osqlda->sqln = 2;
osqlda->version = 1;
/* Allocate a statement handle. */
isc_dsql_allocate_statement(
status_vector,
&database_handle,
&stmt);
Return_if_Error(status_vector);
/* Prepare the query for execution. */
isc_dsql_prepare(
status_vector,
&tr_handle,
&stmt,
0,
sel_str,
1,
osqlda);
Return_if_Error(status_vector);
/* Set up an XSQLVAR structure to allocate space for each item
to be retrieved. */
osqlda->sqlvar[0].sqldata = (char *) dept_no;
osqlda->sqlvar[0].sqltype = SQL_TEXT + 1;
osqlda->sqlvar[0].sqlind = &flag0;
osqlda->sqlvar[1].sqldata = (char *) &array_id;
osqlda->sqlvar[1].sqltype = SQL_ARRAY + 1;
osqlda->sqlvar[1].sqlind = &flag1;
/* Execute the SELECT statement. */
isc_dsql_execute(
status_vector,
&tr_handle,
&stmt,
1,

192 INTERBASE 5
USING FUNCTION DEFINITIONS

NULL);
Return_if_Error(status_vector);
/* Set up the array descriptor. */
isc_array_lookup_bounds(
status_vector,
&database_handle, /* Set by previous isc_attach_database() call. */
&tr_handle, /* Set by previous isc_start_transaction() call. */
"PROJ_DEPT_BUDGET", /* Table name. */
"QUARTERLY_HEAD_CNT", /* Array column name. */
&desc);
Return_if_Error(status_vector);

/* Fetch the head count for each department’s four quarters. */

while ((fetch_stat = isc_dsql_fetch(
status_vector,
&stmt,
1,
osqlda)) == 0)
{
if (!flag1)
{
/* There is array data; get the current values. */
len = sizeof(hcnt);
/* Fetch the data from the array column into hcnt array. */
isc_array_get_slice(
status_vector,
&database_handle,
&tr_handle,
&array_id,
&desc,
hcnt,
&len);
Return_if_Error(status_vector);

/* Print department number and head counts. */

dept_no[osqlda->sqlvar[0].sqllen] = ’\0’;
printf("Department #: %s\n\n", dept_no);
printf("\tCurrent counts: %d %d %d %d\n",
hcnt[0], hcnt[1], hcnt[2], hcnt[3]);
};
}
if (fetch_stat != 100L)
{
SQLCODE = isc_sqlcode(status_vector);

API GUIDE 193

 CHAPTER 12 API FUNCTION REFERENCE

isc_print_sqlerror(SQLCODE, status_vector);
return(1);
}

5HWXUQ9DOXH isc_array_get_slice()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRLVFBEDGBVWPWBKDQGOH
LVFBEDGBWUDQVBKDQGOHRUDQRWKHU,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_array_lookup_bounds()isc_array_lookup_desc()isc_array_put_slice()
isc_array_set_desc(), isc_dsql_fetch()isc_dsql_prepare()

194 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_array_lookup_bounds()
'HWHUPLQHVWKHGDWDW\SHOHQJWKVFDOHGLPHQVLRQVDQGDUUD\ERXQGDULHVIRUWKHVSHFLILHG
DUUD\FROXPQLQWKHVSHFLILHGWDEOH

6\QWD[ ISC_STATUS isc_array_lookup_bounds(

ISC_STATUS *status_vector,
isc_db_handle *db_handle,
isc_tr_handle *trans_handle,
char *table_name,
char *column_name,
ISC_ARRAY_DESC *desc);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
db_handle isc_db_handle * Pointer to a database handle set by a previous call to
isc_attach_database(); the handle identifies the
database containing the array column
db_handle returns an error in status_vector if it is NULL
trans_handle isc_tr_handle * Pointer to a transaction handle whose value has been set
by a previous isc_start_transaction() call;
trans_handle returns an error if NULL
table_name char * Name of the table containing the array column,
column_name; can be either null-terminated or
blank-terminated
column_name char * Name of the array column; can be either null-terminated
or blank-terminated
desc ISC_ARRAY_DESC * Pointer to a descriptor for the arrays that will be filled in
by this function

'HVFULSWLRQ isc_array_lookup_bounds()GHWHUPLQHVWKHGDWDW\SHOHQJWKVFDOHGLPHQVLRQVDQGDUUD\
ERXQGDULHVIRUWKHHOHPHQWVLQDQDUUD\FROXPQFROXPQBQDPHLQWKHWDEOHWDEOHBQDPH,W
VWRUHVWKLVLQIRUPDWLRQLQWKHDUUD\GHVFULSWRUGHVF
isc_array_lookup_bounds()DOVRVHWVWRDIODJLQWKHGHVFULSWRU7KLVVSHFLILHVWKDWWKH
DUUD\VKRXOGEHDFFHVVHGLQIXWXUHIXQFWLRQFDOOVLQURZPDMRURUGHUWKHGHIDXOW,IDQ
DSSOLFDWLRQUHTXLUHVFROXPQPDMRUDFFHVVUHVHWWKLVIODJWR

API GUIDE 195

 CHAPTER 12 API FUNCTION REFERENCE

7KHDUUD\GHVFULSWRULVXVHGLQVXEVHTXHQWFDOOVWRisc_array_get_slice()RU
isc_array_put_slice()
)RUDGHWDLOHGGHVFULSWLRQRIWKHDUUD\GHVFULSWRUVHH&KDSWHU´:RUNLQJZLWK$UUD\'DWDµ
Note 7KHUHDUHZD\VWRILOOLQDQDUUD\GHVFULSWRURWKHUWKDQE\FDOOLQJ
isc_array_lookup_bounds()<RXFDQDOVR
g &DOOisc_array_lookup_desc()7KLVLVH[DFWO\WKHVDPHDV calling
isc_array_lookup_bounds()H[FHSWWKDWWKHIRUPHUGRHVQRWILOOLQLQIRUPDWLRQDERXWWKH
XSSHUDQGORZHUERXQGVRIHDFKGLPHQVLRQ
g &DOOisc_array_set_desc()WRLQLWLDOL]HWKHGHVFULSWRUIURPSDUDPHWHUV\RXFDOOLWZLWKUDWKHU
WKDQDFFHVVLQJWKHGDWDEDVHPHWDGDWD
g 6HWWKHGHVFULSWRUILHOGVGLUHFWO\1RWHWKDWDUUD\BGHVFBGW\SHPXVWEHH[SUHVVHGDVRQHRIWKH
GDWDW\SHVLQWKHIROORZLQJWDEOHDQGWKHSDUDPHWHUVDUUD\BGHVFBILHOGBQDPHDQG
DUUD\BGHVFBUHODWLRQBQDPHPXVWEHQXOOWHUPLQDWHG

array_desc_dtype Corresponding InterBase datatype

blr_text CHAR

blr_text2 CHAR

blr_short SMALLINT

blr_long INTEGER

blr_quad ISC_QUAD structure

blr_float FLOAT

blr_double DOUBLE PRECISION

blr_date DATE

blr_varying VARCHAR

blr_varying2 VARCHAR

blr_blob_id ISC_QUAD structure

blr_cstring NULL-terminated string

blr_cstring2 NULL-terminated string

TABLE 12.13 Datatypes for array descriptor fields

196 INTERBASE 5
USING FUNCTION DEFINITIONS

([DPSOH 7KHIROORZLQJLOOXVWUDWHVDVDPSOHFDOOWRisc_array_lookup_bounds()0RUHFRPSOHWH
H[DPSOHVRIDFFHVVLQJDUUD\VDUHIRXQGLQWKHH[DPSOHSURJUDPVIRUisc_array_get_slice()
DQGisc_array_put_slice()
#include <ibase.h>

ISC_STATUS status_vector[20];
ISC_ARRAY_DESC desc;
char *str1 = "PROJ_DEPT_BUDGET";
char *str2 = "QUARTERLY_HEAD_CNT";

isc_array_lookup_bounds(
status_vector,
&database_handle, /* Set in previous isc_attach_database() call. */
&tr_handle, /* Set in previous isc_start_transaction() call. */
str1,
str2,
&desc);
if (status_vector[0] == 1 && status_vector[1])
{
/* Process error. */
isc_print_status(status_vector);
return(1);
}

5HWXUQ9DOXH isc_array_lookup_bounds()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HUR
LQGLFDWHVVXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQW
RIWKHVWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRLVFBEDGBVWPWBKDQGOH
LVFBEDGBWUDQVBKDQGOHLVFBIOGBQRWBGHIRUDQRWKHU,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_array_get_slice()isc_array_lookup_desc()isc_array_put_slice()
isc_array_set_desc()

API GUIDE 197

 CHAPTER 12 API FUNCTION REFERENCE

isc_array_lookup_desc()
'HWHUPLQHVWKHGDWDW\SHOHQJWKVFDOHDQGGLPHQVLRQVIRUDOOHOHPHQWVLQWKHVSHFLILHGDUUD\
FROXPQLQWKHVSHFLILHGWDEOH

6\QWD[ ISC_STATUS isc_array_lookup_desc(

ISC_STATUS *status_vector,
isc_db_handle *db_handle,
isc_tr_handle *trans_handle,
char *table_name,
char *column_name,
ISC_ARRAY_DESC *desc);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
db_handle isc_db_handle * Pointer to a database handle set by a previous call to
isc_attach_database(); the handle identifies the
database containing the array column
db_handle returns an error in status_vector if it is NULL
trans_handle isc_tr_handle * Pointer to a transaction handle whose value has been set
by a previous isc_start_transaction() call;
trans_handle returns an error if NULL
table_name char * Name of the table containing the array column
column_name; can be either null-terminated or
blank-terminated
column_name char * Name of the array column; can be either null-terminated
or blank-terminated
desc ISC_ARRAY_DESC * Pointer to an array descriptor that will be filled in by this
function

'HVFULSWLRQ isc_array_lookup_desc()GHWHUPLQHVWKHGDWDW\SHOHQJWKVFDOHDQGGLPHQVLRQVIRUWKH
DUUD\FROXPQFROXPQBQDPHLQWKHWDEOHWDEOHBQDPH,WVWRUHVWKLVLQIRUPDWLRQLQWKHDUUD\
GHVFULSWRUGHVF
,WDOVRVHWVWRDIODJLQWKHGHVFULSWRU7KLVVSHFLILHVWKDWWKHDUUD\LVDFFHVVHGLQIXWXUH
IXQFWLRQFDOOVLQURZPDMRURUGHUWKHGHIDXOW,IDQDSSOLFDWLRQUHTXLUHVFROXPQPDMRUDFFHVV
UHVHWWKLVIODJWR

198 INTERBASE 5
USING FUNCTION DEFINITIONS

7KHDUUD\GHVFULSWRULVXVHGLQVXEVHTXHQWFDOOVWRisc_array_get_slice()RU
isc_array_put_slice()
)RUDGHWDLOHGGHVFULSWLRQRIWKHDUUD\GHVFULSWRUVHH&KDSWHU´:RUNLQJZLWK$UUD\'DWDµ
Note 7KHUHDUHZD\VWRILOOLQDQDUUD\GHVFULSWRURWKHUWKDQE\FDOOLQJ
isc_array_lookup_desc()<RXFDQDOVR
g &DOOisc_array_lookup_bounds()7KLVLVOLNHisc_array_lookup_desc()H[FHSWWKDW
isc_array_lookup_bounds()DOVRILOOVLQLQIRUPDWLRQDERXWWKHXSSHUDQGORZHUERXQGVRI
HDFKGLPHQVLRQ
g &DOOisc_array_set_desc()WRLQLWLDOL]HWKHGHVFULSWRUIURPSDUDPHWHUV\RXFDOOLWZLWKUDWKHU
WKDQDFFHVVLQJWKHGDWDEDVHPHWDGDWD
g 6HWWKHGHVFULSWRUILHOGVGLUHFWO\1RWHWKDWDUUD\BGHVFBGW\SHPXVWEHH[SUHVVHGDVRQHRIWKH
GDWDW\SHVLQWKHIROORZLQJWDEOHDQGWKHSDUDPHWHUVDUUD\BGHVFBILHOGBQDPHDQG
DUUD\BGHVFBUHODWLRQBQDPHPXVWEHQXOOWHUPLQDWHG

array_desc_dtype Corresponding InterBase datatype

blr_text CHAR

blr_text2 CHAR

blr_short SMALLINT

blr_long INTEGER

blr_quad ISC_QUAD structure

blr_float FLOAT

blr_double DOUBLE PRECISION

blr_date DATE

blr_varying VARCHAR

blr_varying2 VARCHAR

blr_blob_id ISC_QUAD structure

blr_cstring NULL-terminated string

blr_cstring2 NULL-terminated string

TABLE 12.14 Datatypes for array descriptor fields

API GUIDE 199

 CHAPTER 12 API FUNCTION REFERENCE

([DPSOH 7KHIROORZLQJLOOXVWUDWHVDVDPSOHFDOOWRisc_array_lookup_desc()0RUHFRPSOHWH
H[DPSOHVRIDFFHVVLQJDUUD\VDUHIRXQGLQWKHH[DPSOHSURJUDPVIRUisc_array_get_slice()
DQGisc_array_put_slice()
#include <ibase.h>
ISC_STATUS status_vector[20];
ISC_ARRAY_DESC desc;
char str1 = "PROJ_DEPT_BUDGET";
char str2 = "QUARTERLY_HEAD_CNT";

isc_array_lookup_desc(
status_vector,
&database_handle, /* Set in previous isc_attach_database() call. */
&tr_handle, /* Set in previous isc_start_transaction() call. */
str1,
str2,
&desc);
if (status_vector[0] == 1 && status_vector[1])
{
/* Process error. */
isc_print_status(status_vector);
return(1);
};

5HWXUQ9DOXH isc_array_lookup_desc()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRLVFBEDGBVWPWBKDQGOH
LVFBEDGBWUDQVBKDQGOHLVFBIOGBQRWBGHIRUDQRWKHU,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_array_get_slice()isc_array_lookup_bounds()isc_array_put_slice()
isc_array_set_desc()

200 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_array_put_slice()
:ULWHVGDWDLQWRDQDUUD\FROXPQ

6\QWD[ ISC_STATUS isc_array_put_slice(

ISC_STATUS *status_vector,
isc_db_handle *db_handle,
isc_tr_handle *trans_handle,
ISC_QUAD *array_id,
ISC_ARRAY_DESC *desc,
void *source_array,
ISC_LONG *slice_length);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
db_handle isc_db_handle * Pointer to a database handle set by a previous call to
isc_attach_database(); the handle identifies the
database containing the array column
db_handle returns an error in status_vector if it is NULL
trans_handle isc_tr_handle * Pointer to a transaction handle whose value has been set
by a previous isc_start_transaction() call;
trans_handle returns an error if NULL
array_id ISC_QUAD * On input, NULL (if you are creating a new array), or the
internal identifier for an array to be modified, as assigned
by the InterBase engine. This internal identifier must
have been determined by previous calls to DSQL
functions.
This function changes array_id to be the identifier for the
array it creates or modifies (see below).
desc ISC_ARRAY_DESC * Descriptor defining the array slice (entire array or subset)
to be written to
source_array void * Pointer to a buffer of length slice_length, that contains
the slice of data that will be copied to the array by this
function
slice_length ISC_LONG * Length, in bytes, of the source_array buffer

API GUIDE 201

 CHAPTER 12 API FUNCTION REFERENCE

'HVFULSWLRQ isc_array_put_slice()ZULWHVGDWDLQWRDQDUUD\FROXPQ<RXFDQHLWKHUVWRUHLQWRDOOWKH
DUUD\HOHPHQWVLQWKDWFROXPQRULQWRDQDUUD\VOLFHDVXEVHWRIFRQWLJXRXVDUUD\HOHPHQWV
7KHERXQGDULHVSDVVHGWRWKHIXQFWLRQLQWKHDUUD\GHVFULSWRUGHVFVSHFLI\ZKLFKHOHPHQWV
DUHWREHVWRUHGLQWR
,QWHU%DVHFRSLHVWKHHOHPHQWVIURPWKHEXIIHUVRXUFHBDUUD\ZKRVHVL]HLVVSHFLILHGE\
VOLFHBOHQJWK
7KHDUUD\LGHQWLILHU DUUD\,' DUUD\BLGVKRXOGEHSDVVHGDV18//LI\RXDUHFDOOLQJ
isc_array_put_slice()WRFUHDWHDQHZDUUD\,I\RXDUHFDOOLQJLWWRPRGLI\DQH[LVWLQJDUUD\
WKHQDUUD\BLGVKRXOGEHWKHLGHQWLILHURIWKHDUUD\WREHPRGLILHG7KLVPXVWKDYHEHHQ
GHWHUPLQHGE\SUHYLRXVFDOOVWR'64/IXQFWLRQV
:KHQisc_array_put_slice()LVFDOOHGZLWKDQDUUD\,'RIDQH[LVWLQJDUUD\LW
 &UHDWHVDQHZDUUD\ZLWKWKHVDPHGLPHQVLRQVERXQGVHWFDVWKHVSHFLILHG
DUUD\DQGFRSLHVWKHH[LVWLQJDUUD\GDWDWRWKHQHZDUUD\
 :ULWHVWKHGDWDIURPWKHDUUD\EXIIHUVRXUFHBDUUD\WRWKHQHZDUUD\ RUVOLFHRI
WKHDUUD\ SHUWKHERXQGVVSHFLILHGLQWKHDUUD\GHVFULSWRUGHVF
 5HWXUQVLQWKHVDPHDUUD\BLGYDULDEOHWKHDUUD\,'RIWKHQHZDUUD\
:KHQisc_array_put_slice()LVFDOOHGZLWKD18//DUUD\,'LW
 &UHDWHVDQHZHPSW\DUUD\ZLWKGLPHQVLRQVERXQGVHWFDVGHFODUHGIRUWKH
DUUD\FROXPQZKRVHQDPHDQGWDEOHQDPHDUHVSHFLILHGLQWKHDUUD\GHVFULSWRU
GHVF
 :ULWHVWKHGDWDIURPWKHDUUD\EXIIHUVRXUFHBDUUD\WRWKHQHZDUUD\ RUVOLFHRI
WKHDUUD\
 5HWXUQVLQWKHDUUD\BLGYDULDEOHWKHDUUD\,'RIWKHQHZDUUD\
1RWHWKDWLQERWKFDVHVDQHZDUUD\LVFUHDWHGDQGLWVDUUD\,'LVUHWXUQHGLQWKHDUUD\BLG
YDULDEOH7KHDUUD\LVWHPSRUDU\XQWLODQ83'$7(RU,16(57VWDWHPHQWLVH[HFXWHGWR
DVVRFLDWHWKHDUUD\ZLWKDSDUWLFXODUFROXPQRIDSDUWLFXODUURZ
<RXFDQPDNHDVLQJOHFDOOWRisc_array_put_slice()WRZULWHDOOWKHGDWD\RXZLVKWRWKHDUUD\
2U\RXPD\FDOOisc_array_put_slice()PXOWLSOHWLPHV
WRVWRUHGDWDLQWRYDULRXVVOLFHVRIWKHDUUD\,QWKLVFDVHHDFKFDOOWRisc_array_put_slice()
DIWHUWKHILUVWFDOOVKRXOGSDVV WKHDUUD\,'RIWKHWHPSRUDU\DUUD\:KHQ
isc_array_put_slice() LVFDOOHGZLWK WKHDUUD\,'RIDWHPSRUDU\DUUD\LWFRSLHVWKHVSHFLILHG
GDWDWRWKHVSHFLILHGVOLFHRIWKHWHPSRUDU\DUUD\ LWZLOOQRWFUHDWHDQHZDUUD\ DQGLWGRHVQ·W
PRGLI\DUUD\BLG
%HIRUHFDOOLQJisc_array_put_slice()WKHUHDUHPDQ\RSHUDWLRQV\RXPXVWGRLQRUGHUWRILOO
LQWKHDUUD\GHVFULSWRUGHVFGHWHUPLQHWKHDSSURSULDWHLQWHUQDODUUD\LGHQWLILHUDUUD\BLGDQG
IHWFKWKHURZVZKRVHDUUD\FROXPQV\RXZDQWWRDFFHVV

202 INTERBASE 5
USING FUNCTION DEFINITIONS

)RUFRPSOHWHVWHSE\VWHSLQVWUXFWLRQVIRUVHWWLQJXSDQDUUD\GHVFULSWRUDQGZULWLQJDUUD\
LQIRUPDWLRQVHH&KDSWHU´:RUNLQJZLWK$UUD\'DWDµ
Note 1HYHUH[HFXWHD'64/VWDWHPHQWWKDWWULHVWRGLUHFWO\VWRUHGDWDLQWRDQDUUD\FROXPQ
7KHRQO\ZD\WRDFFHVVDUUD\FROXPQGDWDLVE\FDOOLQJisc_array_get_slice()RU
isc_array_put_slice()7KHRQO\VXSSRUWHGDUUD\UHIHUHQFHVLQ'64/VWDWHPHQWVDUHRQHV
WKDWVSHFLI\DQHQWLUHDUUD\FROXPQ WKDWLVMXVWWKHFROXPQQDPH LQRUGHUWRJHWWKHLQWHUQDO
LGHQWLILHUIRUWKHDUUD\ZKLFKLVUHTXLUHGE\isc_array_get_slice()DQG
isc_array_put_slice()

([DPSOH 7KHIROORZLQJSURJUDPRSHUDWHVRQDWDEOHQDPHG352-B'(37B%8'*(77KLVWDEOH
FRQWDLQVWKHTXDUWHUO\KHDGFRXQWVDOORFDWHGIRUHDFKSURMHFWLQHDFKGHSDUWPHQWRIDQ
RUJDQL]DWLRQ(DFKURZRIWKHWDEOHDSSOLHVWRDSDUWLFXODUGHSDUWPHQWDQGSURMHFW7KH
TXDUWHUO\KHDGFRXQWVDUHFRQWDLQHGLQDQDUUD\FROXPQQDPHG48$57(5/<B+($'B&17
(DFKWDEOHURZKDVIRXUHOHPHQWVLQWKLVFROXPQRQHSHUTXDUWHU(DFKHOHPHQWLVDQXPEHU
RIW\SHORQJ
7KLVSURJUDPVHOHFWVWKHURZVFRQWDLQLQJLQIRUPDWLRQIRUWKHSURMHFWQDPHG9%$6(
)RUHDFKVXFKURZLWFDOOVisc_array_get_slice()WRUHWULHYHDVOLFHRIWKHDUUD\WKHTXDUWHUO\
KHDGFRXQWVIRUWKHODVWWZRTXDUWHUV,WWKHQLQFUHPHQWVHDFKDQGFDOOV
isc_array_put_slice()WRVWRUHWKHXSGDWHGYDOXHV
,QDGGLWLRQWRLOOXVWUDWLQJWKHXVDJHRIisc_array_lookup_desc()isc_array_get_slice(),
DQGisc_array_put_slice()WKHSURJUDPVKRZVGDWDVWUXFWXUHLQLWLDOL]DWLRQVDQGFDOOVWRWKH
'64/IXQFWLRQVUHTXLUHGWRSUHSDUHDQGH[HFXWHWKH6(/(&7DQG83'$7(VWDWHPHQWVWR
REWDLQWKHDUUD\BLGQHHGHGE\isc_array_get_slice()DQGisc_array_put_slice()WRIHWFKWKH
VHOHFWHGURZVRQHE\RQHDQGWRXSGDWHWKHDUUD\,'
#include <ibase.h>

#define Return_if_Error(stat) if (stat[0] == 1 && stat[1]) \

{ \
isc_print_status(stat); \
return(1); \
}

char *sel_str =
"SELECT dept_no, quarterly_head_cnt FROM proj_dept_budget \
WHERE year = 1994 AND proj_id = ’VBASE’";
char *upd_str =
"UPDATE proj_dept_budget SET quarterly_head_count = ? \
WHERE CURRENT OF S";

char dept_no[6];
long fetch_stat, SQLCODE, hcnt[2];

API GUIDE 203

 CHAPTER 12 API FUNCTION REFERENCE

short len, i, flag0, flag1, flag2;

ISC_QUAD array_id;
ISC_ARRAY_DESC desc;
ISC_STATUS status_vector[20];
isc_stmt_handle stmt = NULL;
isc_stmt_handle ustmt = NULL;
char *cursor = "S";
XSQLDA *osqlda, *isqlda;

/* Set up the SELECT statement. */

/* Allocate the output XSQLDA for holding the array data. */

osqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(2));
osqlda->sqln = 2;
osqlda->version = SQLDA_VERSION1;

/* Allocate a statement handle for the SELECT statement. */

isc_dsql_allocate_statement(
status_vector, &database_handle, &stmt);
Return_if_Error(status_vector);

/* Prepare the query for execution. */

isc_dsql_prepare(
status_vector,
&tr_handle,
&stmt,
0,
sel_str,
1,
osqlda);
Return_if_Error(status_vector);

/* Set up an XSQLVAR structure to allocate space for each item

to be retrieved. */

osqlda->sqlvar[0].sqldata = (char *) dept_no;

osqlda->sqlvar[0].sqltype = SQL_TEXT + 1;
osqlda->sqlvar[0].sqlind = &flag0;

osqlda->sqlvar[1].sqldata = (char *) &array_id;

osqlda->sqlvar[1].sqltype = SQL_ARRAY + 1;
osqlda->sqlvar[1].sqlind = &flag1;

/* Execute the SELECT statement. */

204 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_dsql_execute(
status_vector,
&tr_handle,
&stmt,
1,
NULL);
Return_if_Error(status_vector);

/* Declare a cursor. */
isc_dsql_set_cursor_name(
status_vector, &stmt, cursor, 0);
Return_if_Error(status_vector);

/* Set up the UPDATE statement. */

/* Allocate a statement handle for the UPDATE statement. */

isc_dsql_allocate_statement(
status_vector, &database_handle, &ustmt);
Return_if_Error(status_vector);

/* Allocate the input XSQLDA. */

isqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(2));
isqlda->sqln = 1;
1sqlda->version = SQLDA_VERSION1;

/* Prepare the UPDATE statement for execution. */

isc_dsql_prepare(
status_vector,
&tr_handle,
&ustmt,
0,
upd_str,
1,
NULL);
Return_if_Error(status_vector);

/* Initialize the input XSQLDA. */

isc_dsql_describe_bind(
status_vector, &ustmt, 1, isqlda);
Return_if_Error(status_vector);

/* Set up the input sqldata and sqlind fields. */

isqlda->sqlvar[0].sqldata = (char *) &array_id;
isqlda->sqlvar[0].sqlind = &flag2;

API GUIDE 205

 CHAPTER 12 API FUNCTION REFERENCE

/* Set up the array descriptor. */

isc_array_lookup_desc(
status_vector,
&database_handle, /* Set by previous isc_attach_database() call. */
&tr_handle, /* Set by previous isc_start_transaction() call. */
"PROJ_DEPT_BUDGET", /* Table name. */
"QUARTERLY_HEAD_CNT", /* Array column name. */
&desc);
Return_if_Error(status_vector);

/* Set the descriptor bounds to those of the slice to be updated, that is,
to those of the last two elements. Assuming the array column was defined
to contain 4 elements, with a lower bound (subscript) of 1 and an upper
bound of 4, the last two elements are at subscripts 3 and 4. */
desc->array_desc_bounds[0].array_bound_lower = 3;
desc->array_desc_bounds[0].array_bound_upper = 4;

/* Fetch and process the rows of interest. */

while ((fetch_stat = isc_dsql_fetch(
status_vector, &stmt, 1, osqlda)) == 0)
{
if (!flag1)
{
/* There is array data; get values for last two quarters. */
len = sizeof(hcnt);
/* Fetch the data from the array slice into hcnt array. */
isc_array_get_slice(
status_vector,
&database_handle,
&tr_handle,
&array_id,
&desc,
hcnt,
&len);
Return_if_Error(status_vector);

/* Add 1 to each count. */

for (i = 0; i < 2; i++)
hcnt[i] = hcnt[i] + 1;

/* Save new values. */

isc_array_put_slice(
status_vector,

206 INTERBASE 5
USING FUNCTION DEFINITIONS

&database_handle,
&tr_handle,
&array_id,
&desc,
hcnt,
&len);
Return_if_Error(status_vector);

/* Update the array ID. */

isc_dsql_execute(
status_vector, &tr_handle, &ustmt, 1, isqlda);
Return_if_Error(status_vector);

};
};
if (fetch_stat != 100L)
{
SQLCODE = isc_sqlcode(status_vector);
isc_print_sqlerror(SQLCODE, status_vector);
return(1);
}

5HWXUQ9DOXH isc_array_put_slice()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRLVFBEDGBVWPWBKDQGOH
LVFBEDGBWUDQVBKDQGOHRUDQRWKHU,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_array_get_slice()isc_array_lookup_bounds()isc_array_lookup_desc()
isc_array_set_desc()
isc_dsql_allocate_statement()isc_dsql_describe_bind()isc_dsql_execute()
isc_dsql_fetch()isc_dsql_prepare()isc_dsql_set_cursor_name()

API GUIDE 207

 CHAPTER 12 API FUNCTION REFERENCE

isc_array_set_desc()
,QLWLDOL]HVDQDUUD\GHVFULSWRU

6\QWD[ ISC_STATUS isc_array_get_slice(

ISC_STATUS *status_vector,
char *table_name,
char *column_name,
short *sql_dtype,
short *sql_length,
short *dimensions,
ISC_ARRAY_DESC *desc);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
table_name char * Blank- or null-terminated name of the table containing
the array column, column_name
column_name char * Name of the array column; this may be either
null-terminated or blank-terminated
sql_dtype short * Pointer to SQL datatype of the array elements
sql_length short * Pointer to length of each array element
dimensions short * Pointer to number of array dimensions
desc ISC_ARRAY_DESC * Array descriptor to be filled in by this function

'HVFULSWLRQ isc_array_set_desc()LQLWLDOL]HVWKHDUUD\GHVFULSWRUGHVFIURPWKHIXQFWLRQSDUDPHWHUV
WDEOHBQDPHFROXPQBQDPHVTOBGW\SHVTOBOHQJWKDQGGLPHQVLRQV
isc_array_set_desc() DOVRVHWVWRDIODJLQWKHGHVFULSWRU7KLVVSHFLILHVWKDWWKHDUUD\LV
DFFHVVHGLQIXWXUHIXQFWLRQFDOOVLQURZPDMRURUGHUWKHGHIDXOW,IDQDSSOLFDWLRQUHTXLUHV
FROXPQPDMRUDFFHVVUHVHWWKLVIODJWR
WDEOHBQDPHDQGFROXPQBQDPHFDQEHHLWKHUQXOOWHUPLQDWHGRUEODQNWHUPLQDWHG7KHQDPHV
VWRUHGLQWKHGHVFULSWRUZLOOEHQXOOWHUPLQDWHG
VTOBGW\SHPXVWEHJLYHQDVDQ64/PDFURFRQVWDQW
7KHDUUD\GHVFULSWRULVXVHGLQVXEVHTXHQWFDOOVWRisc_array_get_slice()RU
isc_array_put_slice()
)RUDGHWDLOHGGHVFULSWLRQRIWKHDUUD\GHVFULSWRUVHH&KDSWHU´:RUNLQJZLWK$UUD\'DWDµ

208 INTERBASE 5
USING FUNCTION DEFINITIONS

Note 7KHUHDUHZD\VWRILOOLQDQDUUD\GHVFULSWRURWKHUWKDQE\FDOOLQJ isc_array_set_desc()

<RXFDQDOVR
g &DOOisc_array_lookup_bounds()7KLVIXQFWLRQLVVLPLODUWRisc_array_lookup_desc()
H[FHSWWKDWisc_array_lookup_bounds() DOVRILOOVLQLQIRUPDWLRQDERXWWKHXSSHUDQGORZHU
ERXQGVRIHDFKGLPHQVLRQ
g &DOOisc_array_lookup_desc()7KLVIXQFWLRQLVVLPLODUWRisc_array_lookup_bounds()
H[FHSWWKDWisc_array_lookup_desc()GRHVQRWILOOLQLQIRUPDWLRQDERXWWKHXSSHUDQGORZHU
ERXQGVRIHDFKGLPHQVLRQ
g 6HWWKHGHVFULSWRUILHOGVGLUHFWO\1RWHWKDWDUUD\BGHVFBGW\SHPXVWEHH[SUHVVHGDVRQHRIWKH
GDWDW\SHVLQWKHIROORZLQJWDEOHDQGWKH
SDUDPHWHUVDUUD\BGHVFBILHOGBQDPHDQGDUUD\BGHVFBUHODWLRQBQDPHPXVWEHQXOOWHUPLQDWHG

array_desc_dtype Corresponding InterBase datatype

blr_text CHAR

blr_text2 CHAR

blr_short SMALLINT

blr_long INTEGER

blr_quad ISC_QUAD structure

blr_float FLOAT

blr_double DOUBLE PRECISION

blr_date DATE

blr_varying VARCHAR

blr_varying2 VARCHAR

blr_blob_id ISC_QUAD structure

blr_cstring NULL-terminated string

blr_cstring2 NULL-terminated string

TABLE 12.15 Datatypes for array descriptor fields

([DPSOH 7KHIROORZLQJLOOXVWUDWHVDVDPSOHFDOOWRisc_array_set_desc()0RUHFRPSOHWHH[DPSOHVRI
DFFHVVLQJDUUD\VDUHIRXQGLQWKHH[DPSOHSURJUDPVIRUisc_array_get_slice()DQG
isc_array_put_slice()
#include <ibase.h>

API GUIDE 209

 CHAPTER 12 API FUNCTION REFERENCE

ISC_STATUS status_vector[20];
ISC_ARRAY_DESC desc;
short dtype = SQL_TEXT;
short len = 8;
short dims = 1;

isc_array_set_desc(
status_vector,
"TABLE1",
"CHAR_ARRAY",
&dtype,
&len,
&dims,
&desc);
if (status_vector[0] == 1 && status_vector[1])
{
/* Process error. */
isc_print_status(status_vector);
return(1);
}

5HWXUQ9DOXH isc_array_set_desc()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_array_get_slice()isc_array_lookup_bounds()isc_array_lookup_desc()
isc_array_put_slice()

210 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_attach_database()
$WWDFKHVWRDQH[LVWLQJGDWDEDVH

6\QWD[ ISC_STATUS isc_attach_database(

ISC_STATUS *status_vector,
short db_name_length,
char *db_name,
isc_db_handle *db_handle,
short parm_buffer_length,
char *parm_buffer);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
db_name_length short Number of bytes in db_name string; if 0, the string is assumed
to be null-terminated
db_name char * Database name
db_handle isc_db_handle * Pointer to a database handle set by this function;
It is recommended that you set db_handle to NULL before
passing it to isc_attach_database()
parm_buffer_length short Number of bytes in the database parameter buffer (DPB)
parm_buffer char * Address of the DPB

'HVFULSWLRQ 7KHisc_attach_database()IXQFWLRQFRQQHFWVWRDQH[LVWLQJGDWDEDVHWRHQDEOHVXEVHTXHQW
SURJUDPDFFHVV,WDOVRRSWLRQDOO\VSHFLILHVYDULRXVRSHUDWLRQDOFKDUDFWHULVWLFVVXFKDVDXVHU
QDPHDQGSDVVZRUGFRPELQDWLRQIRUDFFHVVWRDGDWDEDVHRQDUHPRWHVHUYHURUWKHQXPEHU
RIGDWDEDVHFDFKHEXIIHUVWRXVH7KHVHRSWLRQDOFKDUDFWHULVWLFVDUHSDVVHGLQDGDWDEDVH
SDUDPHWHUEXIIHU '3% VXSSOLHGDQGSRSXODWHGE\WKHFDOOLQJSURJUDPHLWKHUWKURXJK
GLUHFWSURJUDPFRQVWUXFWLRQDQGE\FDOOLQJisc_expand_dpb()WREXLOGWKH'3%
$SURJUDPSDVVHVWKHQDPHRIWKHGDWDEDVHILOHWRZKLFKWRDWWDFKLQGEBQDPH)RUSURJUDPV
QRWZULWWHQLQ&WKHSURJUDPPXVWDOVRSDVVWKHOHQJWKLQE\WHVRIGEBQDPHLQWKH
GEBQDPHBOHQJWKSDUDPHWHU&SURJUDPVVKRXOGSDVVDOHQJWKLQWKLVSDUDPHWHU
,IVXFFHVVIXOisc_attach_database() DVVLJQVDXQLTXH,'WRGEBKDQGOH6XEVHTXHQW$3,FDOOV
XVHWKLVKDQGOHWRLGHQWLI\WKHGDWDEDVHDJDLQVWZKLFKWKH\RSHUDWH
:KHQILQLVKHGDFFHVVLQJDGDWDEDVHGLVFRQQHFWIURPWKHGDWDEDVHZLWK
isc_detach_database()

API GUIDE 211

 CHAPTER 12 API FUNCTION REFERENCE

([DPSOH 7KHIROORZLQJSURJUDPIUDJPHQWDWWDFKHVWRDGDWDEDVHQDPHGHPSOR\HHGE,QWKHSDUDPHWHU
EXIIHULWVSHFLILHVDXVHUQDPHDQGSDVVZRUG7KHVHFRPHIURPWKHFRQWHQWVRIFKDU*
YDULDEOHVQDPHGXVHUBQDPHDQGXVHUBSDVVZRUGUHVSHFWLYHO\
char dpb_buffer[256], *dpb, *p;
ISC_STATUS status_vector[20];
isc_db_handle handle = NULL;
short dpb_length;

/* Construct the database parameter buffer. */

dpb = dpb_buffer;
*dpb++ = isc_dpb_version1;

*dpb++ = isc_dpb_user_name;
*dpb++ = strlen(user_name);
for (p = user_name; *p;)
*dpb++ = *p++;

*dpb++ = isc_dpb_password;
*dpb++ = strlen(user_password);
for (p = user_password; *p;)
*dpb++ = *p++;
/* An alternate choice for the above construction is to call:
isc_expand_dpb(). */

dpb_length = dpb - dpb_buffer;

isc_attach_database(
status_vector,
0,
"employee.db",
&handle,
dpb_length,
dpb_buffer);
if (status_vector[0] == 1 && status_vector[1])
{
/* An error occurred. */
isc_print_status (status_vector);
return(1);
}

5HWXUQ9DOXH isc_attach_database()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH

212 INTERBASE 5
USING FUNCTION DEFINITIONS

7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_detach_database(), isc_expand_dpb()

)RUPRUHLQIRUPDWLRQDERXWFUHDWLQJDQGSRSXODWLQJD'3%VHH´&UHDWLQJDQGSRSXODWLQJD
'3%µRQSDJH )RUPRUHLQIRUPDWLRQDERXWDWWDFKLQJWRDGDWDEDVHVHH´&RQQHFWLQJWR
GDWDEDVHVµRQSDJH 

isc_blob_default_desc()
/RDGVDGDWDVWUXFWXUHZLWKGHIDXOWLQIRUPDWLRQDERXWD%ORELQFOXGLQJLWVVXEW\SHFKDUDFWHU
VHWDQGVHJPHQWVL]H
void isc_blob_default_desc(
ISC_BLOB_DESC *desc,
unsigned char *table_name,
unsigned char *column_name);

Parameter Type Description

desc ISC_BLOB_DESC * Pointer to a Blob descriptor
table_name unsigned char * Table name
column_name unsigned char * Blob column name

'HVFULSWLRQ isc_blob_default_desc()ORDGVD%OREGHVFULSWRUGHVFZLWKWKHVSHFLILHGWDEOHBQDPHDQG
FROXPQBQDPHDQGWKHIROORZLQJGHIDXOWYDOXHVSULRUWRFDOOLQJisc_blob_gen_bpb()WR
JHQHUDWHD%ORESDUDPHWHUEXIIHU %3% IRUWKH%OREFROXPQEHLQJDFFHVVHG
g 6XEW\SHLVVHWWR7(;7
g &KDUDFWHUVHWLVVHWWRWKHGHIDXOWFKDUDFWHUVHWIRUWKHSURFHVVRUGDWDEDVH
g 6HJPHQWVL]HLVVHWWRE\WHV
isc_blob_default_desc()DQGWKUHHUHODWHGIXQFWLRQVisc_blob_gen_bpb()
isc_blob_lookup_desc()DQGisc_blob_set_desc()SURYLGHG\QDPLFDFFHVVWR%ORE
LQIRUPDWLRQ,QSDUWLFXODUWKHVHIXQFWLRQVFDQGHILQHDQGDFFHVVLQIRUPDWLRQDERXWD%ORE
IRUILOWHULQJSXUSRVHVVXFKDVFKDUDFWHUVHWLQIRUPDWLRQIRUWH[W%OREGDWDDQGVXEW\SH
LQIRUPDWLRQIRUWH[WDQGQRQWH[W%OREGDWD

API GUIDE 213

 CHAPTER 12 API FUNCTION REFERENCE

7KHIROORZLQJWDEOHOLVWVWKHILHOGVLQWKHGHVFVWUXFWXUH

Parameter Type Description

blob_desc_subtype short Subtype of the Blob filter
blob_desc_charset short Character set being used
blob_desc_segment_size short Blob segment size
blob_desc_field_name [32] char Array containing the name of the Blob column
blob_desc_relation_name [32] char Array containing the name of the table in which the
Blob is stored
TABLE 12.16 Blob descriptor fields

([DPSOH 7KHIROORZLQJIUDJPHQWORDGVWKH%OREGHVFULSWRUZLWKGHIDXOWLQIRUPDWLRQ
typedef struct
{
short blob_desc_subtype;
short blob_desc_charset;
short blob_desc_segment_size;
unsigned char blob_desc_field_name[32];
unsigned char blob_desc_relation_name[32];
ISC_BLOB_DESC;
isc_blob_default_desc(&desc, &relation, &field);

5HWXUQ9DOXH 1RQH

6HH$OVR isc_blob_gen_bpb(), isc_blob_lookup_desc() isc_blob_set_desc()

)RUPRUHLQIRUPDWLRQDERXW%OREGHVFULSWRUVVHH&KDSWHU´:RUNLQJZLWK%ORE'DWDµ

214 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_blob_gen_bpb()
*HQHUDWHVD%ORESDUDPHWHUEXIIHU %3% WRDOORZG\QDPLFDFFHVVWR%OREVXEW\SHDQG
FKDUDFWHUVHWLQIRUPDWLRQ

6\QWD[ ISC_STATUS isc_blob_gen_bpb(

ISC_STATUS *status_vector,
ISC_BLOB_DESC *to_desc,
ISC_BLOB_DESC *from_desc,
unsigned short bpb_buffer_length,
unsigned char *bpb_buffer,
unsigned short *bpb_length);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
to_desc ISC_BLOB_DESC * Pointer to the target Blob descriptor
from_desc ISC_BLOB_DESC * Pointer to the source Blob descriptor
bpb_buffer_length unsigned short Length of the BPB bpb_buffer
bpb_buffer unsigned char * Pointer to the BPB
bpb_length unsigned short * Pointer to the length of the data stored into the BPB

'HVFULSWLRQ isc_blob_gen_bpb()JHQHUDWHVD%ORESDUDPHWHUEXIIHU %3% IURPVXEW\SHDQGFKDUDFWHU

VHWLQIRUPDWLRQVWRUHGLQWKHVRXUFH%OREGHVFULSWRUIURPBGHVFDQGWKHWDUJHW GHVWLQDWLRQ 
%OREGHVFULSWRUWRBGHVF
$%3%LVQHHGHGZKHQHYHUDILOWHUZLOOEHXVHGZKHQZULWLQJWRRUUHDGLQJIURPD%ORE
FROXPQ7ZR%OREGHVFULSWRUVDUHQHHGHGIRUILOWHULQJRQH IURPBGHVF WRGHVFULEHWKHILOWHU
VRXUFHGDWDDQGWKHRWKHU WRBGHVF WRGHVFULEHWKHGHVWLQDWLRQ7KHGHVFULSWRUVPXVWKDYH
EHHQSUHYLRXVO\FUHDWHGHLWKHUGLUHFWO\RUYLDDFDOOWRisc_blob_default_desc()
isc_blob_lookup_desc()RUisc_blob_set_desc()
7KH%3%JHQHUDWHGE\isc_blob_gen_bpb()LVVXEVHTXHQWO\QHHGHGLQFDOOVWR
isc_open_blob2() RU isc_create_blob2()LIILOWHULQJZLOOEHXWLOL]HG)RUPRUHLQIRUPDWLRQ
DERXWWKH%3%VHH&KDSWHU´:RUNLQJZLWK%ORE'DWDµ

([DPSOH 7KHIROORZLQJIUDJPHQWJHQHUDWHVWKH%OREGHVFULSWRU
isc_blob_gen_bpb(status, &to_desc, &from_desc, bpb_length, &buffer,
&buf_length);

API GUIDE 215

 CHAPTER 12 API FUNCTION REFERENCE

5HWXUQ9DOXH isc_blob_gen_bpb()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_blob_default_desc()isc_blob_lookup_desc()isc_blob_set_desc()
isc_create_blob2()isc_open_blob2()

isc_blob_info()
5HWXUQVLQIRUPDWLRQDERXWDQRSHQ%ORE

6\QWD[ ISC_STATUS isc_blob_info(

ISC_STATUS *status_vector,
isc_blob_handle *blob_handle,
short item_list_buffer_length,
char *item_list_buffer,
short result_buffer_length,
char *result_buffer);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
blob_handle isc_blob_handle * Pointer to the Blob
item_list_buffer_length short Length of the item-list buffer in which you specify
the items for which you want information
item_list_buffer char * Pointer to the item-list buffer
result_buffer_length short Length of the result buffer into which InterBase
returns the requested information
result_buffer char * Pointer to the result buffer

'HVFULSWLRQ isc_blob_info()UHWXUQVLQIRUPDWLRQDERXWDQH[LVWLQJ%OREVSHFLILHGE\EOREBKDQGOH7KH
LWHPOLVWEXIIHULVDQXQVWUXFWXUHGE\WHYHFWRU$QDSSOLFDWLRQOLVWVWKHLWHPVDERXWZKLFKLW
ZDQWVLQIRUPDWLRQLQWKHLWHPOLVWEXIIHU

216 INTERBASE 5
USING FUNCTION DEFINITIONS

,QWHU%DVHUHWXUQVWKHUHTXHVWHGLQIRUPDWLRQWRWKHUHVXOWEXIIHUDVDVHULHVRIFOXVWHUVRI
LQIRUPDWLRQRQHSHULWHPUHTXHVWHG(DFKFOXVWHUFRQVLVWVRIWKUHHSDUWV
 $RQHE\WHLWHPW\SH(DFKLVWKHVDPHDVRQHRIWKHLWHPW\SHVLQWKHLWHPOLVW
EXIIHU
 $E\WHQXPEHUVSHFLI\LQJWKHQXPEHURIE\WHVWKDWIROORZLQWKHUHPDLQGHURI
WKHFOXVWHU
 $YDOXHVWRUHGLQDYDULDEOHQXPEHURIE\WHVZKRVHLQWHUSUHWDWLRQGHSHQGVRQ
WKHLWHPW\SH
$FDOOLQJSURJUDPLVUHVSRQVLEOHIRULQWHUSUHWLQJWKHFRQWHQWVRIWKHUHVXOWEXIIHUDQGIRU
GHFLSKHULQJHDFKFOXVWHUDVDSSURSULDWH
)RUDOLVWRILWHPVWKDWFDQEHUHTXHVWHGDQGUHWXUQHGVHH&KDSWHU´:RUNLQJZLWK%ORE
'DWDµ

([DPSOH 7KHIROORZLQJH[DPSOHUHWULHYHVLQIRUPDWLRQDERXWWKHFXUUHQWRSHQ%ORE
static char blob_items[] = {
isc_info_blob_max_segment,
isc_info_blob_num_segments,
isc_info_blob_type};

CHAR blob_info[32];

isc_open_blob2(status_vector, &db, &tr_handle, &blob_handle, &blob_id,

blength, baddr)
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector);
return(1);
}
isc_blob_info(status_vector, &blob_handle, sizeof(blob_items),
blob_items, sizeof(blob_info), blob_info));

5HWXUQ9DOXH isc_blob_info()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHVVXFFHVV$
QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKHVWDWXVYHFWRU
LVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_create_blob2() isc_open_blob2()

API GUIDE 217

 CHAPTER 12 API FUNCTION REFERENCE

isc_blob_lookup_desc()
'HWHUPLQHVWKHVXEW\SHFKDUDFWHUVHWDQGVHJPHQWVL]HRID%OREJLYHQDWDEOHQDPHDQG
%OREFROXPQQDPH

6\QWD[ ISC_STATUS isc_blob_lookup_desc(

ISC_STATUS *status_vector,
isc_db_handle **db_handle,
isc_tr_handle **trans_handle,
unsigned char *table_name,
unsigned char *column_name,
ISC_BLOB_DESC *desc,
unsigned char *global);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
db_handle isc_db_handle ** Pointer to a database handle set by a previous call to
isc_attach_database()
db_handle returns an error in status_vector if it is NULL
trans_handle isc_tr_handle ** Pointer to a transaction handle whose value has been set by a
previous isc_start_transaction() call; trans_handle returns an
error if NULL
table_name unsigned char * Name of the table containing the Blob column
column_name unsigned char * Name of the Blob column
desc ISC_BLOB_DESC * Pointer to the Blob descriptor to which the function returns
information
global unsigned char * Global column name, returned by this function

'HVFULSWLRQ isc_blob_lookup_desc()XVHVWKHV\VWHPWDEOHVRIDGDWDEDVHWRGHWHUPLQHWKHVXEW\SH
FKDUDFWHUVHWDQGVHJPHQWVL]HRID%OREJLYHQDWDEOHQDPHDQG%OREFROXPQQDPH
isc_blob_lookup_desc()DQGWKUHHUHODWHGIXQFWLRQVisc_blob_default_desc()
isc_blob_gen_bpb()DQGisc_blob_set_desc()SURYLGHG\QDPLFDFFHVVWR%ORE
LQIRUPDWLRQ,QSDUWLFXODU\RXFDQXVHWKHVHIXQFWLRQVWRGHILQHDQGDFFHVVLQIRUPDWLRQ
DERXW%OREGDWDIRUILOWHULQJSXUSRVHVVXFKDVFKDUDFWHUVHWLQIRUPDWLRQIRUWH[W%OREGDWD
DQGVXEW\SHLQIRUPDWLRQIRUWH[WDQGQRQWH[W%OREGDWD

218 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_blob_lookup_desc()VWRUHVWKHUHTXHVWHGLQIRUPDWLRQDERXWWKH%ORELQWRWKHGHVF%ORE
GHVFULSWRUVWUXFWXUH7KHIROORZLQJWDEOHGHVFULEHVWKHGHVFVWUXFWXUH

Parameter Type Description

blob_desc_subtype short Subtype of the Blob filter
blob_desc_charset short Character set being used
blob_desc_segment_size short Blob segment size
blob_desc_field_name [32] char Array containing the name of the Blob column
blob_desc_relation_name [32] char Array containing the name of the table in which the
Blob is stored
TABLE 12.17 Blob descriptor fields

([DPSOH 7KHIROORZLQJIUDJPHQWUHWULHYHVLQIRUPDWLRQLQWRD%OREGHVFULSWRU
isc_blob_lookup_desc(status, &db_handle, &tr_handle, &relation_name,
&field_name, desc, &global);

5HWXUQ9DOXH isc_blob_lookup_desc()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH7RFKHFN
IRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\)RUPRUH
LQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_blob_default_desc()isc_blob_gen_bpb()isc_blob_set_desc()
)RUPRUHLQIRUPDWLRQDERXW%OREGHVFULSWRUVVHH&KDSWHU´:RUNLQJZLWK%ORE'DWDµ

API GUIDE 219

 CHAPTER 12 API FUNCTION REFERENCE

isc_blob_set_desc()
6HWVWKHVXEW\SHDQGFKDUDFWHUVHWIRUD%ORE

6\QWD[ ISC_STATUS isc_blob_set_desc(

ISC_STATUS *status_vector,
unsigned char *table_name,
unsigned char *column_name,
short subtype,
short charset,
short segment_size,
ISC_BLOB_DESC *desc);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
table_name unsigned char * Name of the table containing the Blob column
column_name unsigned char * Name of the Blob column in the table
subtype short Specifies the subtype of the Blob; value are:
• InterBase-defined subtype values, 0 or 1 ( TEXT )
• User-defined subtypes, –1 to –32768
charset short Specifies the character set for the Blob
segment_size short Specifies the segment size for the Blob
desc ISC_BLOB_DESC * Pointer to a Blob descriptor to populate.

'HVFULSWLRQ isc_blob_set_desc()VHWVWKH%OREFROXPQQDPHWDEOHQDPHVXEW\SHVHJPHQWVL]HDQG
FKDUDFWHUVHWIRUD%OREFROXPQWRYDOXHVVSHFLILHGE\WKHDSSOLFDWLRQ7RVHWWKHVHYDOXHVWR
,QWHU%DVHGHIDXOWVXVHisc_blob_default_desc()
isc_blob_set_desc()DQGWKUHHUHODWHGIXQFWLRQVisc_blob_default_desc()
isc_blob_gen_bpb()DQGisc_blob_lookup_desc()SURYLGHG\QDPLFDFFHVVWR%OREGDWD
,QSDUWLFXODU\RXFDQXVHWKHVHIXQFWLRQVWRGHILQHDQGDFFHVVLQIRUPDWLRQDERXW%OREGDWD
IRUILOWHULQJSXUSRVHVVXFKDVFKDUDFWHUVHWLQIRUPDWLRQIRUWH[W%OREGDWDDQGVXEW\SH
LQIRUPDWLRQIRUWH[WDQGQRQWH[W%OREGDWD
<RXFDQPDQXDOO\VHWWKHVXEW\SHDQGFKDUDFWHUVHWLQIRUPDWLRQ IRUD7(;7VXEW\SH LQD
%OREGHVFULSWRUE\ZD\RIDFDOOWRisc_blob_set_desc()3DVVWKHVXEW\SHFKDUDFWHUVHWDQG
VHJPHQWVL]HWRWKH%OREGHVFULSWRULQ\RXUDSSOLFDWLRQ

220 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_blob_set_desc()LVXVHIXOIRUVHWWLQJWKHFRQWHQWVRIWKH%OREGHVFULSWRUZLWKRXW
TXHU\LQJWKHV\VWHPWDEOHVIRUWKHLQIRUPDWLRQ&DOOVWRWKLVIXQFWLRQDOVROHWDQDSSOLFDWLRQ
VSHFLI\FKDUDFWHUVHWDQGVXEW\SHIRUFXVWRPILOWHULQJRSHUDWLRQV
Note 'RQRWFDOOWKLVIXQFWLRQZKLOHUXQQLQJDJDLQVWD9[GDWDEDVH

([DPSOH 7KHIROORZLQJH[DPSOHVHWVWKHGHIDXOWYDOXHVIRUDWRXUJXLGHDSSOLFDWLRQLQFOXGLQJ
VXEW\SHFKDUDFWHUVHWDQGVHJPHQWVL]H
isc_blob_set_desc(status, "TOURISM", "GUIDEBOOK", 1, 2, 80, &desc);

5HWXUQ9DOXH isc_blob_set_desc()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_blob_default_desc() isc_blob_gen_bpb() isc_blob_lookup_desc()

)RUPRUHLQIRUPDWLRQDERXW%OREGHVFULSWRUVVHH&KDSWHU´:RUNLQJZLWK%ORE'DWDµ

isc_cancel_blob()
'LVFDUGVD%OREIUHHVLQWHUQDOVWRUDJHXVHGE\WKH%OREDQGVHWVWKH%OREKDQGOHWR18//

6\QWD[ ISC_STATUS isc_cancel_blob(

ISC_STATUS *status_vector,
isc_blob_handle *blob_handle);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
blob_handle isc_blob_handle * Pointer to the handle for the Blob you want to cancel; sets the
handle to zero and returns a successful result even if the
handle is NULL.

API GUIDE 221

 CHAPTER 12 API FUNCTION REFERENCE

'HVFULSWLRQ ,QWHU%DVHWHPSRUDULO\VWRUHV%OREGDWDLQWKHGDWDEDVHGXULQJFUHDWHRSHUDWLRQV,IIRUVRPH
UHDVRQ\RXGRQRWRUFDQQRWFORVHD%OREWKHVWRUDJHVSDFHUHPDLQVDOORFDWHGLQWKH
GDWDEDVHDQG,QWHU%DVHGRHVQRWVHWWKHKDQGOHWR18//&DOOisc_cancel_blob()WRUHOHDVH
WKHWHPSRUDU\VWRUDJHLQWKHGDWDEDVHDQGWRVHWEOREBKDQGOHWR18//,I\RXFORVHWKH%ORE
LQWKHQRUPDOFRXUVHRI\RXUDSSOLFDWLRQSURFHVVLQJORJLFWKLVVWHSLVXQQHFHVVDU\DV
,QWHU%DVHUHOHDVHVV\VWHPUHVRXUFHVRQDFDOOWRisc_close_blob()
Note $FDOOWRWKLVIXQFWLRQGRHVQRWSURGXFHDQHUURUZKHQWKHKDQGOHLV18//7KHUHIRUH
LWLVJRRGSUDFWLFHWRFDOOisc_cancel_blob()EHIRUHFUHDWLQJRURSHQLQJD%OREWRFOHDQXS
H[LVWLQJ%ORERSHUDWLRQV

([DPSOH 7KHIROORZLQJIUDJPHQWFDQFHOVDQ\RSHQ%OREEHIRUHFUHDWLQJDQHZRQH
isc_cancel_blob(status_vector, &blob_handle);
if (status_vector[0] == 1 && status_vector[1])
{
/* process error */
isc_print_status(status_vector);
return(1);
}
isc_create_blob(status_vector, &DB, &trans, &blob_handle, &blob_id)

5HWXUQ9DOXH isc_cancel_blob()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHVVXFFHVV
$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKHVWDWXV
YHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_close_blob()

222 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_cancel_events()
&DQFHOVDQDSSOLFDWLRQ·VLQWHUHVWLQDV\QFKURQRXVQRWLILFDWLRQRIDQ\RIDVSHFLILHGJURXSRI
HYHQWV

6\QWD[ ISC_STATUS isc_cancel_events(

ISC_STATUS *status_vector,
isc_db_handle *db_handle,
ISC_LONG *event_id);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
db_handle isc_db_handle * Pointer to a database handle set by a previous call to
isc_attach_database(); the handle identifies the database for
which the event watch is to be canceled.
db_handle returns an error in status_vector if it is NULL
event_id ISC_LONG * Pointer to the event or events to cancel; set by a previous call to
isc_que_events()

'HVFULSWLRQ isc_cancel_events()FDQFHOVDQDSSOLFDWLRQSURJUDP·VDV\QFKURQRXVZDLWIRUDQ\RID
VSHFLILHGOLVWRIHYHQWV7KHHYHQWVDUHWKHRQHVWKDWZHUHDVVRFLDWHGZLWKHYHQWBLGDVDUHVXOW
RIDSUHYLRXVFDOOWRisc_que_events()

([DPSOH 7KHIROORZLQJFDOOFDQFHOVDSURJUDP·VZDLWIRUHYHQWVDVVRFLDWHGZLWKHYHQWBLGZKHUHHYHQWBLG
ZDVSUHYLRXVO\UHWXUQHGIURPDFDOOWRisc_que_events()
isc_cancel_events(status_vector, &database_handle, &event_id);
$PRUHFRPSOHWHH[DPSOHLVSURYLGHGLQWKHVHFWLRQRQisc_que_events()

5HWXUQ9DOXH isc_cancel_events()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_que_events()

API GUIDE 223

 CHAPTER 12 API FUNCTION REFERENCE

isc_close_blob()
&ORVHVDQRSHQ%OREZKLFKLQYROYHVIOXVKLQJDQ\UHPDLQLQJVHJPHQWVUHOHDVLQJV\VWHP
UHVRXUFHVDVVRFLDWHGZLWK%OREXSGDWHRUUHWULHYDODQGVHWWLQJWKH%OREKDQGOHWR]HUR

6\QWD[ ISC_STATUS isc_close_blob(

ISC_STATUS *status_vector,
isc_blob_handle *blob_handle);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
blob_handle isc_blob_handle * Pointer to the handle of the Blob to close

'HVFULSWLRQ isc_close_blob()LVXVHGWRVWRUHD%ORELQWKHGDWDEDVHDQGFOHDQXSDIWHU%ORERSHUDWLRQV
&ORVHDQ\%OREDIWHUUHDGLQJIURPRUZULWLQJWRLW,IIRUVRPHUHDVRQ\RXUDSSOLFDWLRQGRHV
QRWFORVHD%ORE\RXFDQORVHGDWD,I\RXUDSSOLFDWLRQPLJKWRSHQD%OREZLWKRXWFORVLQJLW
WKHQ\RXVKRXOGFDOOisc_cancel_blob()WRPDNHVXUHWKDWWKHDSSOLFDWLRQGRHVQRWWU\WR
RSHQD
%OREWKDWLVDOUHDG\RSHQ
EOREBKDQGOHLVVHWE\DFDOOWRisc_create_blob2()RUWRisc_open_blob2()

([DPSOH 7KHIROORZLQJH[DPSOHFORVHVD%OREDQGIUHHVV\VWHPUHVRXUFHV
if (status_vector[1] == isc_segstr_eof)
isc_close_blob(status_vector, &blob_handle)

5HWXUQ9DOXH isc_close_blob()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHVVXFFHVV$
QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKHVWDWXVYHFWRU
LVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_cancel_blob()isc_create_blob2()isc_open_blob2()

224 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_commit_retaining()
&RPPLWVDQDFWLYHWUDQVDFWLRQDQGUHWDLQVWKHWUDQVDFWLRQFRQWH[WDIWHUDFRPPLW

6\QWD[ ISC_STATUS isc_commit_retaining(

ISC_STATUS *status_vector,
isc_tr_handle *trans_handle);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
trans_handle isc_tr_handle * Pointer to a transaction handle whose value has been set by a
previous isc_start_transaction() call; trans_handle returns
an error if NULL

'HVFULSWLRQ isc_commit_retaining()FRPPLWVDQDFWLYHWUDQVDFWLRQDQGLPPHGLDWHO\FORQHVLWVHOI7KLV
PHDQVWKDWWKHIXQFWLRQUHWDLQVWKHWUDQVDFWLRQQDPHV\VWHPUHVRXUFHVDVVRFLDWHGZLWKWKH
WUDQVDFWLRQDQGWKHFXUUHQWVWDWHRIDQ\RSHQFXUVRUVLQWKHWUDQVDFWLRQ$OWKRXJKWKH
IXQFWLRQLVDFWXDOO\LQLWLDWLQJDQHZWUDQVDFWLRQE\DVVLJQLQJWKHQHZWUDQVDFWLRQWKHDFWLYH
WUDQVDFWLRQKDQGOHLWLVLQHIIHFWNHHSLQJWKHWUDQVDFWLRQRSHQDFURVVFRPPLWV7KLVUHVXOWV
LQLPSURYHGSHUIRUPDQFHE\DOORZLQJDQDSSOLFDWLRQWRPLQLPL]HWKHRYHUKHDGRILQLWLDWLQJ
DGGLWLRQDOWUDQVDFWLRQVisc_commit_retaining()DOORZV\RXWRFRPPLWXSGDWHVZKLOH
NHHSLQJDFXUVRURSHQ
<RXFDQLQLWLDWHDUROOEDFNZLWKLQWKHDFWLYHWUDQVDFWLRQEXWWKHUROOEDFNRQO\DIIHFWV
XQFRPPLWWHGXSGDWHV,QRWKHUZRUGVDUROOEDFNLVOHJDOHYHQDIWHUWKHWUDQVDFWLRQFRQWH[W
KDVEHHQSDVVHGWRWKHFORQHGWUDQVDFWLRQEXWLQWKDWFDVHWKHUROOEDFNZLOORQO\DIIHFWWKH
XSGDWHV\RXUDSSOLFDWLRQKDVPDGHWRWKHGDWDEDVHVLQFHWKHODVWFRPPLW
7RDXGLWWKHFRPPLWVPDGHE\\RXUFDOOVWRWKLVIXQFWLRQFKHFNWKHILUVWHOHPHQWLQWKHVWDWXV
YHFWRUWRVHHLIWKHFDOOZDVVXFFHVVIXO,IWKLVHOHPHQWFRQWDLQVD]HURWKHFDOOZDVVXFFHVVIXO
7KHWUDQVDFWLRQHQGVZKHQ\RXFRPPLWZLWKRXWXVLQJWKHUHWHQWLRQIHDWXUHVXFKDVZLWKD
FDOOWRisc_commit_transaction()RUZKHQ\RXUROOEDFNZLWKisc_rollback_transaction()

([DPSOH 7KHIROORZLQJFDOOFRPPLWVDWUDQVDFWLRQSULQWVDPHVVDJHDQGVWDUWVDQHZWUDQVDFWLRQZLWK
WKHVDPHKDQGOHZLWKLQWKHVDPHUHTXHVW
if (!isc_commit_retaining(status, &retained_trans))
{
fprintf("Committed and retained\\n");
isc_print_status(status);
}

API GUIDE 225

 CHAPTER 12 API FUNCTION REFERENCE

7KHIROORZLQJFDOOFRPPLWVDWUDQVDFWLRQSULQWVDFRQILUPDWLRQPHVVDJHVWDUWVDQHZ
WUDQVDFWLRQZLWKWKHVDPHKDQGOHZLWKLQWKHVDPHUHTXHVWRULIWKHFRPPLWIDLOVSULQWVDQ
HUURUPHVVDJHDQGUROOVEDFN
isc_commit_retaining(status, &retained_trans);
if (status[0] == 1 && status[1])
{
fprintf("An error occurred during commit, rolling back.");
rb_status = isc_rollback_transaction(status, &retained_status);
}
else
{
fprintf("Commit successful.");
tr_count++; /*Increments the number of commits. */
}

5HWXUQ9DOXH isc_commit_retaining()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_commit_transaction()isc_rollback_transaction()isc_start_transaction()

isc_commit_transaction()
&RPPLWVDVSHFLILHGDFWLYHWUDQVDFWLRQ

6\QWD[ ISC_STATUS isc_commit_transaction(

ISC_STATUS *status_vector,
isc_tr_handle *trans_handle);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
trans_handle isc_tr_handle * Pointer to a transaction handle whose value has been set by a
previous isc_start_transaction() call; trans_handle returns
an error if NULL

226 INTERBASE 5
USING FUNCTION DEFINITIONS

'HVFULSWLRQ isc_commit_transaction() FORVHVUHFRUGVWUHDPVIUHHVV\VWHPUHVRXUFHVDQGVHWVWKH

WUDQVDFWLRQKDQGOHWR]HURIRUWKHVSHFLILHGWUDQVDFWLRQ
:KHQ\RXFDOOWKLVIXQFWLRQWRH[HFXWHDFRPPLWRSHUDWLRQDJDLQVWPXOWLSOHGDWDEDVHV
,QWHU%DVHILUVWLQLWLDWHVDFDOOWRWKHisc_prepare_transaction()IXQFWLRQ
isc_prepare_transaction()H[HFXWHVWKHILUVWSKDVHRIDWZRSKDVHFRPPLW7KLVSXWVWKH
WUDQVDFWLRQLQWROLPERDQGVLJQDOV\RXULQWHQWLRQWRFRPPLWVRWKDW,QWHU%DVHFDQSROODOO
WDUJHWGDWDEDVHVWRYHULI\WKDWWKH\DUHUHDG\WRDFFHSWWKHFRPPLW$OVR
isc_commit_transaction()ZULWHVD%OREPHVVDJHWRWKH
5'%75$16$&7,21B'(6&5,37,21FROXPQRIWKH5'%75$16$&7,216V\VWHPWDEOH
GHWDLOLQJLQIRUPDWLRQUHTXLUHGE\,QWHU%DVHWRSHUIRUPDUHFRQQHFWLQFDVHRIV\VWHPIDLOXUH
GXULQJWKHFRPPLWSURFHVV
7KHisc_commit_transaction()IXQFWLRQDOVRSHUIRUPVWKHVHFRQGSKDVHRIDWZRSKDVH
FRPPLWXSRQUHFHLYLQJYHULILFDWLRQWKDWDOOGDWDEDVHVDUHUHDG\WRDFFHSWWKHFRPPLW$OVR
isc_commit_transaction()FOHDQVXS5'%75$16$&7,216

([DPSOH 7KHIROORZLQJFDOOFRPPLWVDWUDQVDFWLRQDQGSULQWVDPHVVDJH
isc_commit_transaction(status, &trans);
if (status[0] == 1 && status[1])
{
fprintf("Error on write\\n");
isc_print_status(status);
}

5HWXUQ9DOXH isc_commit_transaction()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_commit_retaining()isc_prepare_transaction()

API GUIDE 227

 CHAPTER 12 API FUNCTION REFERENCE

isc_create_blob2()
&UHDWHVDQGRSHQVWKH%OREIRUZULWHDFFHVVDQGRSWLRQDOO\VSHFLILHVWKHILOWHUVWREHXVHGWR
WUDQVODWHWKH%OREIURPRQHVXEW\SHWRDQRWKHU

6\QWD[ ISC_STATUS isc_create_blob2(

ISC_STATUS *status_vector,
isc_db_handle *db_handle,
isc_tr_handle *trans_handle,
isc_blob_handle *blob_handle,
ISC_QUAD *blob_id,
short bpb_length,
char *bpb_address);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
db_handle isc_db_handle * Pointer to a database handle set by a previous call to
isc_attach_database()
db_handle returns an error in status_vector if it is NULL
trans_handle isc_tr_handle * Pointer to the handle of the transaction in which you want the
Blob to be created
blob_handle isc_blob_handle * Pointer to the Blob handle
blob_id ISC_QUAD * Pointer to the 64-bit system-defined Blob ID, which is stored
in a field in the table and points to the first segment of the
Blob or to a page of pointers to Blob fragments
bpb_length short Length of the Blob parameter buffer (BPB)
bpb_address char * Pointer to the BPB

'HVFULSWLRQ isc_create_blob2()FUHDWHVDFRQWH[WIRUVWRULQJD%ORERSHQVD%OREIRUZULWHDFFHVVDQG
RSWLRQDOO\VSHFLILHVWKHILOWHUVXVHGWRWUDQVODWHIURPRQH%OREIRUPDWWRDQRWKHU
6XEVHTXHQWFDOOVWRisc_put_segment()ZULWHGDWDIURPDQDSSOLFDWLRQEXIIHUWRWKH%ORE
,ID%OREILOWHULVXVHGLWLVFDOOHGIRUHDFKVHJPHQWZULWWHQWRWKH%ORE,QWHU%DVHVHOHFWVWKH
ILOWHUWREHXVHGEDVHGRQWKHVRXUFHDQGWDUJHWVXEW\SHVVSHFLILHGLQDSUHYLRXVO\SRSXODWHG
%ORESDUDPHWHUEXIIHU %3% SRLQWHGWRE\ESEBDGGUHVV
Note %OREILOWHUVDUHQRWVXSSRUWHGRQ1HWZDUH

228 INTERBASE 5
USING FUNCTION DEFINITIONS

,ID%OREILOWHULVQRWQHHGHGRUFDQQRWEHXVHGD%3%LVQRWQHHGHGSDVVIRUESEBOHQJWK
DQG18//IRUESEBDGGUHVV
7KH%OREKDQGOHSRLQWHGWRE\EOREBKDQGOHPXVWEH]HURZKHQisc_create_blob2() LVFDOOHG
7RUHXVHEOREBKDQGOHFORVHWKH%OREZLWKDFDOOWRisc_close_blob()WR]HURRXWWKHKDQGOH
EHIRUHFDOOLQJ isc_create_blob2()
2QVXFFHVVisc_create_blob2()DVVLJQVDXQLTXH,'WREOREBKDQGOHDQGD%ORELGHQWLILHUWR
EOREBLG6XEVHTXHQW$3,FDOOVUHTXLUHRQHRUERWKRIWKHVHWRLGHQWLI\WKH%OREDJDLQVWZKLFK
WKH\RSHUDWH
$IWHUDEORELVFUHDWHGGDWDFDQEHZULWWHQWRLWE\DVHTXHQFHRIFDOOVWRisc_put_segment()
:KHQILQLVKHGZULWLQJWRWKH%OREFORVHLWZLWKisc_close_blob()
:KHQ\RXFUHDWHD%ORELWLVHVVHQWLDOO\DQ´RUSKDQµXQWLO\RXDVVLJQLWVEOREBLGWRDSDUWLFXODU
%OREFROXPQRIDSDUWLFXODUURZRIDWDEOH<RXGRWKLVDIWHUFORVLQJWKH%OREE\XVLQJ'64/
WRH[HFXWHHLWKHUDQ,16(57VWDWHPHQWWRLQVHUWDQHZURZFRQWDLQLQJWKH%ORE DQGDQ\RWKHU
FROXPQVGHVLUHG RUDQ83'$7(VWDWHPHQWWRUHSODFHDQH[LVWLQJ%OREZLWKWKHQHZRQH
)RUPRUHLQIRUPDWLRQDERXW%3%VDQG%OREILOWHUVVHH&KDSWHU´:RUNLQJZLWK%ORE
'DWDµ

([DPSOH 7KHIROORZLQJIUDJPHQWGHFODUHVD%3%SRSXODWHVLWZLWKILOWHULQIRUPDWLRQWKHQFUHDWHVD
%OREDQGSDVVHVWKH%3%
isc_blob_handle blob_handle; /* declare at beginning */
ISC_QUAD blob_id; /* declare at beginning */
char bpb[] = {
isc_bpb_version1,
isc_bpb_target_type,
1, /* # bytes that follow which specify target subtype */
1, /* target subtype (TEXT) */
isc_bpb_source_type,
1, /* # bytes that follow which specify source subtype */
-4, /* source subtype*/
};

. . .

isc_create_blob2(
status_vector,
&db_handle,
&tr_handle,
&blob_handle, /* to be filled in by this function */
&blob_id, /* to be filled in by this function */
actual_bpb_length, /* length of BPB data */

API GUIDE 229

 CHAPTER 12 API FUNCTION REFERENCE

&bpb /* Blob parameter buffer */

)

5HWXUQ9DOXH isc_create_blob2()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHVVXFFHVV
$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKHVWDWXV
YHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_blob_gen_bpb()isc_open_blob2()isc_put_segment()

isc_database_info()
5HSRUWVUHTXHVWHGLQIRUPDWLRQDERXWDSUHYLRXVO\DWWDFKHGGDWDEDVH

6\QWD[ ISC_STATUS isc_database_info(

ISC_STATUS *status_vector,
isc_db_handle *db_handle,
short item_list_buffer_length,
char *item_list_buffer,
short result_buffer_length,
char *result_buffer);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector.
db_handle isc_db_handle * Pointer to a database handle set by a previous call to
isc_attach_database()
db_handle returns an error in status_vector if it is
NULL

item_list_buffer_length short Number of bytes in the item-list buffer.

item_list_buffer char * Address of the item-list buffer.
result_buffer_length short Number of bytes in the result buffer.
result_buffer char * Address of the result buffer.

'HVFULSWLRQ isc_database_info()UHWXUQVLQIRUPDWLRQDERXWDQDWWDFKHGGDWDEDVH7\SLFDOO\
isc_database_info()LVFDOOHGWR

230 INTERBASE 5
USING FUNCTION DEFINITIONS

g 'HWHUPLQHKRZPXFKVSDFHLVXVHGIRUSDJHFDFKHV7KHVSDFHLVWKHSURGXFWRIWKHQXPEHU
RIEXIIHUVDQGWKHSDJHVL]HZKLFKDUHGHWHUPLQHGE\FDOOLQJisc_database_info()ZLWKWKH
LVFBLQIRBQXPBEXIIHUVDQGLVFBLQIRBSDJHBVL]HLWHPOLVWRSWLRQV
g 0RQLWRUSHUIRUPDQFH)RUH[DPSOHWRFRPSDUHWKHHIILFLHQF\RIWZRXSGDWHVWUDWHJLHVVXFK
DVXSGDWLQJDVRUWHGRUXQVRUWHGVWUHDP
7KHFDOOLQJSURJUDPSDVVHVLWVUHTXHVWIRULQIRUPDWLRQWKURXJKWKHLWHPOLVWEXIIHUVXSSOLHG
E\WKHSURJUDPDQG,QWHU%DVHUHWXUQVWKHLQIRUPDWLRQWRDSURJUDPVXSSOLHGUHVXOWEXIIHU

([DPSOH 7KHIROORZLQJSURJUDPIUDJPHQWUHTXHVWVWKHSDJHVL]HDQGWKHQXPEHURIEXIIHUVWKHQ
H[DPLQHVWKHUHVXOWEXIIHUWRUHWULHYHWKHYDOXHVVXSSOLHGE\WKH,QWHU%DVHHQJLQH
char db_items[] = {
isc_info_page_size, isc_info_num_buffers,
isc_info_end};
char res_buffer[40], *p, item;
int length;
SLONG page_size = 0L, num_buffers = 0L;
ISC_STATUS status_vector[20];

isc_database_info(
status_vector,
&handle, /* Set in previous isc_attach_database() call. */
sizeof(db_items),
db_items,
sizeof(res_buffer),
res_buffer);
if (status_vector[0] == 1 && status_vector[1])
{
/* An error occurred. */
isc_print_status(status_vector);
return(1);
};
/* Extract the values returned in the result buffer. */
for (p = res_buffer; *p != isc_info_end ;)
{
item = *p++;
length = isc_vax_integer (p, 2);
p += 2;
switch (item)
{
case isc_info_page_size:
page_size = isc_vax_integer (p, length);
break;

API GUIDE 231

 CHAPTER 12 API FUNCTION REFERENCE

case isc_info_num_buffers:
num_buffers = isc_vax_integer (p, length);
break;
default:
break;
}
p += length;
};

5HWXUQ9DOXH isc_database_info()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_attach_database()isc_detach_database()
)RUPRUHLQIRUPDWLRQDERXWUHTXHVWLQJGDWDEDVHDWWDFKPHQWLQIRUPDWLRQVHH´5HTXHVWLQJ
LQIRUPDWLRQDERXWDQDWWDFKPHQWµRQSDJH 

isc_decode_date()
7UDQVODWHVDGDWHIURP,QWHU%DVH,6&B48$'IRUPDWLQWRWKH&WPIRUPDW

6\QWD[ void isc_decode_date(

ISC_QUAD *ib_date,
void *tm_date);

Parameter Type Description

ib_date ISC_QUAD * Pointer to an eight-byte ISC_QUAD structure containing a date in
InterBase format.
tm_date void * Pointer to a C tm structure.

'HVFULSWLRQ isc_decode_date()WUDQVODWHVDGDWHUHWULHYHGIURPDWDEOHDQGVWRUHGLQDQ,6&B48$'
YDULDEOHLEBGDWHLQWRD&WLPHVWUXFWXUHIRUSURJUDPPDQLSXODWLRQ%RWKLEBGDWHDQGWPBGDWH
PXVWEHGHFODUHGDQGLQLWLDOL]HGEHIRUHXVH
8VHWKHisc_dsqlIDPLO\RI$3,FDOOVWRUHWULHYH,QWHU%DVH'$7(GDWDIURPDWDEOHLQWRWKH
,6&B48$'VWUXFWXUHSULRUWRWUDQVODWLRQ

232 INTERBASE 5
USING FUNCTION DEFINITIONS

([DPSOH 7KHIROORZLQJFRGHIUDJPHQWLOOXVWUDWHVGHFODULQJWLPHVWUXFWXUHVDQGFDOOLQJ
isc_decode_date()WRWUDQVODWHDQ,QWHU%DVHGDWHIRUPDWLQWRD&WLPHIRUPDW
#include <time.h>
#include <ibase.h>
. . .
struct tm hire_time;
ISC_QUAD hire_date;
. . .
/* Retrieve DATE data from a table here. */
. . .
isc_decode_date(&hire_date, &hire_time);

5HWXUQ9DOXH 1RQH

6HH$OVR isc_encode_date()

isc_delete_user( )
'HOHWHVDXVHUUHFRUGIURPWKHSDVVZRUGGDWDEDVHLVFJGE

6\QWD[ ISC_STATUS isc_delete_user(

ISC_STATUS *status
USER_SEC_DATA *user_sec_data);

Parameter Type Description

status vector ISC_STATUS * Pointer to the error status vector.
user_sec_data USER_SEC_DATA * Pointer to a struct that is defined in ibase.h.

'HVFULSWLRQ 7KHWKUHHVHFXULW\IXQFWLRQVisc_add_user()isc_delete_user()DQGisc_modify_user()
PLUURUIXQFWLRQDOLW\WKDWLVDYDLODEOHLQWKHgsecFRPPDQGOLQHXWLOLW\isc_delete_user()
GHOHWHVDUHFRUGIURPLVFJGE,QWHU%DVH·VSDVVZRUGGDWDEDVH
$WDPLQLPXP\RXPXVWSURYLGHWKHXVHUQDPH,IWKHVHUYHULVQRWORFDO\RXPXVWSURYLGH
ERWKDVHUYHUQDPHDQGDSURWRFRO9DOLGFKRLFHVIRUWKHSURWRFROILHOGDUHVHFBSURWRFROBWFSLS
VHFBSURWRFROBQHWEHXLVHFBSURWRFROBVS[DQGVHFBSURWRFROBORFDO
,QWHU%DVHUHDGVWKHVHWWLQJVIRUWKH,6&B86(5DQG,6&B3$66:25'HQYLURQPHQWYDULDEOHVLI
\RXGRQRWSURYLGHD'%$XVHUQDPHDQGSDVVZRUG

API GUIDE 233

 CHAPTER 12 API FUNCTION REFERENCE

7KHGHILQLWLRQIRUWKH86(5B6(&B'$7$VWUXFWLQLEDVHKLVDVIROORZV
typedef struct {
short sec_flags; /* which fields are specified */
int uid; /* the user’s id */
int gid; /* the user’s group id */
int protocol; /* protocol to use for connection */
char *server; /* server to administer */
char *user_name; /* the user’s name */
char *password; /* the user’s password */
char *group_name; /* the group name */
char *first_name; /* the user’s first name */
char *middle_name; /* the user’s middle name */
char *last_name; /* the user’s last name */
char *dba_user_name; /* the dba user name */
char *dba_password; /* the dba password */
} USER_SEC_DATA;

:KHQ\RXSDVVWKLVVWUXFWWRRQHRIWKHWKUHHVHFXULW\IXQFWLRQV\RXFDQWHOOLWZKLFKILHOGV
\RXKDYHVSHFLILHGE\GRLQJDELWZLVH25RIWKHIROORZLQJYDOXHVZKLFKDUHGHILQHGLQLEDVHK
sec_uid_spec 0x01
sec_gid_spec 0x02
sec_server_spec 0x04
sec_password_spec 0x08
sec_group_name_spec 0x10
sec_first_name_spec 0x20
sec_middle_name_spec 0x40
sec_last_name_spec 0x80
sec_dba_user_name_spec 0x100
sec_dba_password_spec 0x200

1RELWYDOXHVDUHDYDLODEOHIRUXVHUQDPHDQGSDVVZRUGVLQFHWKH\DUHUHTXLUHG

234 INTERBASE 5
USING FUNCTION DEFINITIONS

7KHIROORZLQJHUURUPHVVDJHVH[LVWIRUWKLVIXQFWLRQ

Code Value Description

isc_usrname_too_long 335544747 The user name passed in is greater than 31 bytes
isc_password_too_long 335544748 The password passed in is longer than 8 bytes
isc_usrname_required 335544749 The operation requires a user name
isc_password_required 335544750 The operation requires a password
isc_bad_protocol 335544751 The protocol specified is invalid
isc_dup_usrname_found 335544752 The user name being added already exists in the security
database.
isc_usrname_not_found 335544753 The user name was not found in the security database
isc_error_adding_sec_record 335544754 An unknown error occurred while adding a user
isc_error_deleting_sec_record 335544755 An unknown error occurred while deleting a user
isc_error_modifying_sec_record 335544756 An unknown error occurred while modifying a user
isc_error_updating_sec_db 335544757 An unknown error occurred while updating the security
database
TABLE 12.18 Error messages for user security functions

([DPSOH 7KHIROORZLQJH[DPSOHGHOHWHVDXVHU ´6RFNVµ IURPWKHSDVVZRUGGDWDEDVHXVLQJWKH

ELWZLVH25WHFKQLTXHIRUSDVVLQJYDOXHVIURPWKH86(5B6(&B'$7$VWUXFW
{
ISC_STATUS status[20];
USER_SEC_DATA sec;

sec.server = "kennel";
sec.dba_user_name = "sysdba";
sec.dba_password = "masterkey";
sec.protocol = sec_protocol_tcpip;
sec.user_name = "socks";
sec.sec_flags = sec_server_spec
| sec_dba_user_name_spec
| sec_dba_password_name_spec;

isc_delete_user(status, &sec);
/* check status for errors */

API GUIDE 235

 CHAPTER 12 API FUNCTION REFERENCE

if (status[0] == 1 && status[1])

{
switch (status[1]) {
case isc_usrname_too_long:
printf("Security database cannot accept long user names\n");
break;
...
}
}
}

5HWXUQ9DOXH isc_delete_user()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHVVXFFHVV
$QRQ]HURYDOXHLQGLFDWHVDQHUURU6HHWKH´'HVFULSWLRQµVHFWLRQIRUWKLVIXQFWLRQIRUDOLVW
RIHUURUFRGHV)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU
´+DQGOLQJ(UURU&RQGLWLRQVµ

6HH$OVR isc_add_user()isc_modify_user()

isc_detach_database()
'HWDFKHVIURPDGDWDEDVHSUHYLRXVO\FRQQHFWHGZLWKisc_attach_database()

6\QWD[ ISC_STATUS isc_detach_database(

ISC_STATUS *status_vector,
isc_db_handle *db_handle);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
db_handle isc_db_handle * Pointer to a database handle set by a previous call to
isc_attach_database()
db_handle returns an error in status_vector if it is NULL

'HVFULSWLRQ isc_detach_database()GHWDFKHVDQDWWDFKHGGDWDEDVH&DOOWKLVIXQFWLRQWRUHOHDVHV\VWHP
UHVRXUFHVZKHQ\RXDUHGRQHXVLQJDGDWDEDVHRUEHIRUHUHDWWDFKLQJWKHGDWDEDVHZLWK
GLIIHUHQWDWWDFKSDUDPHWHUV isc_detach_database()DOVRUHOHDVHVWKHEXIIHUVDQGVWUXFWXUHV
WKDWFRQWUROWKHUHPRWHLQWHUIDFHRQWKHFOLHQWDQGWKHUHPRWHVHUYHUZKHUHWKHGDWDEDVHLV
VWRUHG
%HIRUHFDOOLQJisc_detach_database()FRPPLWRUUROOEDFNWUDQVDFWLRQVDIIHFWLQJWKH
GDWDEDVHIURPZKLFK\RXZDQWWRGHWDFK

236 INTERBASE 5
USING FUNCTION DEFINITIONS

([DPSOH 7KHIROORZLQJFRQGLWLRQDOVWDWHPHQWGHWDFKHVDGDWDEDVH
if (handle)
isc_detach_database(status_vector, &handle);

$VVXPLQJWKDWKDQGOHLVYDOLGDQGLGHQWLILHVDQDWWDFKHGGDWDEDVHWKHVSHFLILHGGDWDEDVHLV
GHWDFKHGZKHQWKLVVWDWHPHQWH[HFXWHV

5HWXUQ9DOXH isc_detach_database()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_attach_database()

isc_drop_database()
'HOHWHVDFXUUHQWO\DWWDFKHGGDWDEDVHDQGDOORILWVVXSSRUWLQJILOHVVXFKDVVHFRQGDU\
GDWDEDVHILOHVZULWHDKHDGORJILOHVDQGVKDGRZILOHV

6\QWD[ ISC_STATUS isc_drop_database(

ISC_STATUS *status_vector,
isc_db_handle *db_handle);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
db_handle isc_db_handle * Pointer to a database handle set by a previous call to
isc_attach_database(); the handle identifies the database
containing the array column
db_handle returns an error in status_vector if it is NULL

'HVFULSWLRQ isc_drop_database()GHOHWHVDQDWWDFKHGGDWDEDVHDQGDOORILWVVXSSRUWLQJILOHV&DOOWKLV
URXWLQHZKHQ\RXQRORQJHUKDYHDXVHIRUWKHGDWDEDVH IRUH[DPSOHLI\RXPRYHGDOOWKH
GDWDLQWRDQRWKHUGDWDEDVHRULIWKHGDWDEDVHZDVMXVWWHPSRUDU\DQGLVQRORQJHUQHHGHG 
7RVXFFHHGisc_drop_database()PXVWEHLVVXHGZKHQQRRWKHUSURFHVVHVDUHDWWDFKHGWR
WKHGDWDEDVH

([DPSOH 7KHIROORZLQJFRQGLWLRQDOVWDWHPHQWGURSVDGDWDEDVH

API GUIDE 237

 CHAPTER 12 API FUNCTION REFERENCE

if (handle)
isc_drop_database(status_vector, &handle);

$VVXPLQJWKDWKDQGOHLVYDOLGDQGLGHQWLILHVDQDWWDFKHGGDWDEDVHWKHVSHFLILHGGDWDEDVHLV
GURSSHGZKHQWKLVVWDWHPHQWH[HFXWHV

5HWXUQ9DOXH isc_drop_database()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_attach_database()

isc_dsql_allocate_statement()
$OORFDWHVDVWDWHPHQWKDQGOHIRUVXEVHTXHQWXVHZLWKRWKHU$3,G\QDPLF64/ '64/ FDOOV

6\QWD[ ISC_STATUS isc_dsql_allocate_statement(

ISC_STATUS *status_vector,
isc_db_handle *db_handle,
isc_stmt_handle *stmt_handle);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
db_handle isc_db_handle * Pointer to a database handle set by a previous call to
isc_attach_database()
db_handle returns an error in status_vector if it is NULL
stmt_handle isc_stmt_handle * Pointer to the statement handle to be allocated by this
function; the handle must be NULL when this function is
called, or an error is returned in status_vector

'HVFULSWLRQ isc_dsql_allocate_statement()DOORFDWHVDVWDWHPHQWKDQGOHDQGUHWXUQVDSRLQWHUWRLWLQ
VWPWBKDQGOH7KLVSRLQWHULVSDVVHGWRisc_dsql_prepare()WRDVVRFLDWHWKHVWDWHPHQWKDQGOH
ZLWKDSDUWLFXODU'64/VWDWHPHQWIRUSURFHVVLQJ

238 INTERBASE 5
USING FUNCTION DEFINITIONS

,ID'64/VWDWHPHQWLVWREHH[HFXWHGPXOWLSOHWLPHVRULILWUHWXUQVRXWSXW RWKHUWKDQWKH
UHVXOWVIURPDVWRUHGSURFHGXUH isc_dsql_allocate_statement()RU
isc_dsql_alloc_statement2()VKRXOGEHFDOOHGWRDOORFDWHDVWDWHPHQWKDQGOHSULRUWR
SUHSDULQJDQGH[HFXWLQJWKHVWDWHPHQWZLWKisc_dsql_prepare()DQGisc_dsql_execute()
Note 7KHIXQFWLRQisc_dsql_allocate_statement()LVYHU\VLPLODUWR WKHIXQFWLRQ,
isc_dsql_alloc_statement2() H[FHSWWKDWVWDWHPHQWKDQGOHVDOORFDWHGXVLQJ
isc_dsql_allocate_statement() DUHQRWDXWRPDWLFDOO\UHVHWWR18//ZKHQWKHGDWDEDVH
XQGHUZKLFKWKH\DUHDOORFDWHGLVGHWDFKHG7RUHVHWVWDWHPHQWKDQGOHVDXWRPDWLFDOO\XVH
isc_dsql_alloc_statement2()
:KHQ\RXDUHGRQHSURFHVVLQJDVWDWHPHQWWKHVWDWHPHQWKDQGOHFDQEHIUHHGZLWKWKH
isc_dsql_free_statement()RUE\FDOOLQJisc_detach_database()

([DPSOH 7KHIROORZLQJSURJUDPIUDJPHQWDOORFDWHVDVWDWHPHQWKDQGOHIRUDQ64/VWDWHPHQWWKDW
ZLOODFFHVVWKHGDWDEDVHUHIHUHQFHGE\WKHGDWDEDVHKDQGOHGDWDEDVHBKDQGOH
ISC_STATUS status_vector[20];
isc_stmt_handle statement_handle;

statement_handle = NULL; /* Set handle to NULL before allocating it. */

isc_dsql_allocate_statement(
status_vector,
&database_handle, /* Set in previous isc_attach_database() call. */
&statement_handle);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector); /* Display error message. */
return(1); /* Return now. */
}
/* Call other functions to associate a particular SQL statement with
the statement handle, and to do other operations necessary to prepare and
execute the DSQL statement. Free the statement handle when it is no longer
needed. */

5HWXUQ9DOXH isc_dsql_allocate_statement()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HUR
LQGLFDWHVVXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQW
RIWKHVWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRLVFBEDGBVWPWBKDQGOH
LVFBEDGBGEBKDQGOHRUDQRWKHU,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

API GUIDE 239

 CHAPTER 12 API FUNCTION REFERENCE

6HH$OVR isc_dsql_alloc_statement2()isc_dsql_execute()isc_dsql_free_statement()
isc_dsql_prepare()

isc_dsql_alloc_statement2()
$OORFDWHVDVWDWHPHQWKDQGOHIRUVXEVHTXHQWXVHZLWKRWKHU$3,G\QDPLF64/ '64/ FDOOV

6\QWD[ ISC_STATUS isc_dsql_alloc_statement2(

ISC_STATUS *status_vector,
isc_db_handle *db_handle,
isc_stmt_handle *stmt_handle);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
db_handle isc_db_handle * Pointer to a database handle set by a previous call to
isc_attach_database(); the handle identifies the database
containing the array column
db_handle returns an error in status_vector if it is NULL
stmt_handle isc_stmt_handle * Pointer to the statement handle to be allocated by this
function; the handle must be NULL when this function is
called, or an error is returned in status_vector

'HVFULSWLRQ isc_dsql_alloc_statement2()DOORFDWHVDVWDWHPHQWKDQGOHDQGUHWXUQVDSRLQWHUWRLWLQ
VWPWBKDQGOH7KLVSRLQWHULVSDVVHGWRisc_dsql_prepare()WRDVVRFLDWHWKHVWDWHPHQWKDQGOH
ZLWKDSDUWLFXODU'64/VWDWHPHQWIRUSURFHVVLQJ
,ID'64/VWDWHPHQWLVWREHH[HFXWHGPXOWLSOHWLPHVRULILWUHWXUQVRXWSXW RWKHUWKDQWKH
UHVXOWVIURPDVWRUHGSURFHGXUH isc_dsql_alloc_statement2()RU
isc_dsql_allocate_statement()VKRXOGEHFDOOHGWRDOORFDWHDVWDWHPHQWKDQGOHSULRUWR
SUHSDULQJDQGH[HFXWLQJWKHVWDWHPHQWZLWKisc_dsql_prepare()DQGisc_dsql_execute()
Note 7KHIXQFWLRQisc_dsql_allocate_statement2()LVYHU\VLPLODUWR WKHIXQFWLRQ,
isc_dsql_alloc_statement() H[FHSWWKDWVWDWHPHQWKDQGOHVDOORFDWHGXVLQJ
isc_dsql_allocate_statement2() DUHDXWRPDWLFDOO\UHVHWWR18//ZKHQWKHGDWDEDVHXQGHU
ZKLFKWKH\DUHDOORFDWHGLVGHWDFKHG

([DPSOH 7KHIROORZLQJSURJUDPIUDJPHQWDOORFDWHVDVWDWHPHQWKDQGOHIRUDQ64/VWDWHPHQWWKDW
ZLOODFFHVVWKHGDWDEDVHUHIHUHQFHGE\WKHGDWDEDVHKDQGOHGDWDEDVHBKDQGOH
ISC_STATUS status_vector[20];
isc_stmt_handle statement_handle;

240 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_dsql_alloc_statement2(
status_vector,
&database_handle, /* Set in previous isc_attach_database() call. */
&statement_handle);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector); /* Display an error message. */
return(1); /* Return now. */
}
/* Call other functions to associate a particular SQL statement with
the statement handle, and to do other operations necessary to prepare and
execute the DSQL statement. */
;

5HWXUQ9DOXH isc_dsql_alloc_statement2()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HUR
LQGLFDWHVVXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQW
RIWKHVWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRLVFBEDGBVWPWBKDQGOH
LVFBEDGBGEBKDQGOHRUDQRWKHU,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_dsql_allocate_statement() isc_dsql_execute() isc_dsql_free_statement()

isc_dsql_prepare()

API GUIDE 241

 CHAPTER 12 API FUNCTION REFERENCE

isc_dsql_describe()
3URYLGHVLQIRUPDWLRQDERXWFROXPQVUHWULHYHGE\WKHH[HFXWLRQRID'64/6(/(&7RU
(;(&87(352&('85(VWDWHPHQW

6\QWD[ ISC_STATUS isc_dsql_describe(

ISC_STATUS *status_vector,
isc_stmt_handle *stmt_handle,
unsigned short dialect,
XSQLDA *xsqlda);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
stmt_handle isc_stmt_handle * Pointer to a statement handle previously allocated with
isc_dsql_allocate_statement() or
isc_dsql_alloc_statement2(); the handle returns an error
in status_vector if it is NULL
dialect unsigned short Indicates the version of the SQL descriptor area passed to the
function; set this value to 1
xsqlda XSQLDA * Pointer to a previously allocated XSQLDA used for output

'HVFULSWLRQ isc_dsql_describe()VWRUHVLQWR[VTOGDDGHVFULSWLRQRIWKHFROXPQVWKDWPDNHXSWKHURZV
UHWXUQHGIRUD6(/(&7VWDWHPHQWRUDGHVFULSWLRQRIWKHUHVXOWYDOXHVUHWXUQHGE\DQ
(;(&87(352&('85(VWDWHPHQW7KHVHVWDWHPHQWVPXVWKDYHEHHQSUHYLRXVO\SUHSDUHG
IRUH[HFXWLRQZLWKisc_dsql_prepare()EHIRUHisc_dsql_describe()FDQEHFDOOHG
Note 8VLQJLVFBGVTOBGHVFULEH LVQRWQHFHVVDU\XQOHVVDSUHYLRXVO\LVVXHG
LVFBGVTOBSUHSDUH IXQFWLRQLQGLFDWHVWKDWWKHUHLVLQVXIILFLHQWURRPLQWKHRXWSXW;64/'$
IRUWKHUHWXUQYDOXHVRIWKH'64/VWDWHPHQWWREHH[HFXWHG

([DPSOH 7KHIROORZLQJSURJUDPIUDJPHQWLOOXVWUDWHVDVHTXHQFHRIFDOOVZKLFKDOORFDWHVDQ;64/'$
SUHSDUHVDVWDWHPHQWFKHFNVZKHWKHURUQRWWKHDSSURSULDWHQXPEHURI;64/9$5VZDV
DOORFDWHGDQGFRUUHFWVWKHVLWXDWLRQLIQHHGHG
#include <ibase.h>
ISC_STATUS status_vector[20];
XSQLDA *osqlda;
int n;
char *query =
"SELECT * FROM CITIES WHERE STATE = "NY" ORDER BY CITY DESCENDING";

242 INTERBASE 5
USING FUNCTION DEFINITIONS

osqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(3);

osqlda->version = SQLDA_VERSION1;
osqlda->sqln = 3;

isc_dsql_prepare(
status_vector,
&tr_handle, /* Set in previous isc_start_transaction() call. */
&stmt_handle,
/* Allocated previously by isc_dsql_allocate_statement()
or isc_dsql_alloc_statement2() call. */
0,
query,
1,
osqlda);
if (status_vector[0] == 1 && status_vector[1])
{
/* Process error. */
isc_print_status(status_vector);
return(1);
}

if (osqlda->sqld > osqlda->sqln) /* Need more XSQLVARS. */

{
n = osqlda->sqld;
free(osqlda);
osqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(n);
osqlda->sqln = n;
osqlda->version = SQLDA_VERSION1;
isc_dsql_describe(
status_vector,
&stmt_handle,
1,
osqlda);
if (status_vector[0] == 1 && status_vector[1])
{
/* Process error. */
isc_print_status(status_vector);
return(1);
}
}

API GUIDE 243

 CHAPTER 12 API FUNCTION REFERENCE

5HWXUQ9DOXH isc_dsql_describe()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRLVFBEDGBVWPWBKDQGOHRUDQRWKHU
,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_dsql_describe_bind()isc_dsql_execute()isc_dsql_execute2()
isc_dsql_prepare()
)RUPRUHLQIRUPDWLRQDERXWSUHSDULQJD'64/VWDWHPHQWZLWKUHWXUQYDOXHVVHH´'64/
SURJUDPPLQJPHWKRGVµRQSDJH )RUPRUHLQIRUPDWLRQDERXWFUHDWLQJDQGSRSXODWLQJ
WKH;64/'$VHH´8QGHUVWDQGLQJWKH;64/'$µRQSDJH 

isc_dsql_describe_bind()
3URYLGHVLQIRUPDWLRQDERXWG\QDPLFLQSXWSDUDPHWHUVUHTXLUHGE\DSUHYLRXVO\SUHSDUHG
'64/VWDWHPHQW

6\QWD[ ISC_STATUS isc_dsql_describe_bind(

ISC_STATUS *status_vector,
isc_stmt_handle *stmt_handle,
unsigned short dialect,
XSQLDA *xsqlda);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
stmt_handle isc_stmt_handle * Pointer to a statement handle previously allocated with
isc_dsql_allocate_statement() or
isc_dsql_alloc_statement2(); the handle returns an error
in status_vector if it is NULL
dialect unsigned short Indicates the version of the SQL descriptor area passed to the
function; set this value to 1
xsqlda XSQLDA * Pointer to a previously allocated XSQLDA used for input

'HVFULSWLRQ isc_dsql_describe_bind()VWRUHVLQWRWKHLQSXW;64/'$[VTOGDLQIRUPDWLRQDERXWWKH
G\QDPLFLQSXWSDUDPHWHUVUHTXLUHGE\D'64/VWDWHPHQWSUHYLRXVO\SUHSDUHGZLWK
isc_dsql_prepare()

244 INTERBASE 5
USING FUNCTION DEFINITIONS

%HIRUHDQDSSOLFDWLRQFDQH[HFXWHDVWDWHPHQWZLWKLQSXWSDUDPHWHUVLWPXVWVXSSO\YDOXHV
IRUWKHPLQDQLQSXW;64/'$VWUXFWXUH,I\RXNQRZH[DFWO\KRZPDQ\SDUDPHWHUVDUH
UHTXLUHGDQGWKHLUGDWDW\SHV\RXFDQVHWXSWKH;64/'$GLUHFWO\ZLWKRXWFDOOLQJ
isc_dsql_describe_bind()%XWLI\RXQHHG,QWHU%DVHWRDQDO\]HWKHVWDWHPHQWDQGSURYLGH
LQIRUPDWLRQVXFKDVWKHQXPEHURISDUDPHWHUVDQGWKHLUGDWDW\SHV\RXPXVWFDOO
isc_dsql_describe_bind()WRVXSSO\WKHLQIRUPDWLRQ

([DPSOH 7KHIROORZLQJSURJUDPIUDJPHQWLOOXVWUDWHVDVHTXHQFHRIFDOOVWKDWDOORFDWHVDQLQSXW
;64/'$SUHSDUHVD'64/83'$7(VWDWHPHQWFDOOVWKHIXQFWLRQ
isc_dsql_describe_bind()FKHFNVZKHWKHURUQRWWKHDSSURSULDWHQXPEHURI;64/9$5V
ZDVDOORFDWHGDQGFRUUHFWVWKHVLWXDWLRQLIQHFHVVDU\
#include <ibase.h>
ISC_STATUS status_vector[20];
XSQLDA *isqlda
int n;
char *str = "UPDATE DEPARTMENT SET BUDGET = ?, LOCATION = ?";

isc_dsql_prepare(
status_vector,
&tr_handle, /* Set in previous isc_start_transaction() call. */
&stmt_handle,
/* Allocated previously by isc_dsql_allocate_statement()
or isc_dsql_alloc_statement2() call. */
0,
str,
1,
NULL);
if (status_vector[0] == 1 && status_vector[1])
{
/* Process error. */
isc_print_status(status_vector);
return(1);
}
/* Allocate an input XSQLDA. */
isqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(1);
isqlda->version = SQLDA_VERSION1;
isqlda->sqln = 1;
isc_dsql_describe_bind(
status_vector,
&stmt_handle,
/* Allocated previously by isc_dsql_allocate_statement()
or isc_dsql_alloc_statement2() call. */
1,

API GUIDE 245

 CHAPTER 12 API FUNCTION REFERENCE

isqlda);
if (status_vector[0] == 1 && status_vector[1])
{
/* Process error. */
isc_print_status(status_vector);
return(1);
}
if (isqlda->sqld > isqlda->sqln) /* Need more XSQLVARs. */
{
n = isqlda->sqld;
free(isqlda);
isqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(n);
isqlda->sqln = n;
isqlda->version = SQLDA_VERSION1;
isc_dsql_describe_bind(
status_vector,
&stmt_handle,
1,
isqlda);
if (status_vector[0] == 1 && status_vector[1])
{
/* Process error. */
isc_print_status(status_vector);
return(1);
}
}

5HWXUQ9DOXH isc_dsql_describe_bind()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRLVFBEDGBVWPWBKDQGOHRUDQRWKHU
,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_dsql_describe()
isc_dsql_execute()
isc_dsql_execute2()isc_dsql_prepare()
)RUPRUHLQIRUPDWLRQDERXWSUHSDULQJD'64/VWDWHPHQWZLWKLQSXWSDUDPHWHUVVHH´'64/
SURJUDPPLQJPHWKRGVµRQSDJH )RUPRUHLQIRUPDWLRQDERXWFUHDWLQJDQGSRSXODWLQJ
WKH;64/'$VHH´8QGHUVWDQGLQJWKH;64/'$µRQSDJH 

246 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_dsql_execute()
([HFXWHVDSUHYLRXVO\SUHSDUHG'64/VWDWHPHQW

6\QWD[ ISC_STATUS isc_dsql_execute(

ISC_STATUS *status_vector,
isc_tr_handle *trans_handle,
isc_stmt_handle *stmt_handle,
unsigned short dialect,
XSQLDA *xsqlda);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
trans_handle isc_tr_handle * Pointer to a transaction handle whose value has been set by a
previous isc_start_transaction() call; trans_handle returns
an error if NULL
stmt_handle isc_stmt_handle * Pointer to a statement handle previously allocated with
isc_dsql_allocate_statement() or
isc_dsql_alloc_statement2(); returns an error in
status_vector if NULL
dialect unsigned short Indicates the version of the extended SQL descriptor area
(XSQLDA) passed to the function; set this value to 1
xsqlda XSQLDA * Pointer to a previously allocated XSQLDA used for input

'HVFULSWLRQ isc_dsql_execute()H[HFXWHVD'64/VWDWHPHQWSUHYLRXVO\SUHSDUHGZLWK
isc_dsql_prepare() isc_dsql_execute()FDQEHXVHGWRH[HFXWHWZRW\SHVRIVWDWHPHQWV
g 6WDWHPHQWVWKDWPD\UHWXUQPRUHWKDQRQHURZRIGDWD
g 6WDWHPHQWVWKDWQHHGWREHH[HFXWHGPRUHWKDQRQFH
,IDVWDWHPHQWWRH[HFXWHKDVLQSXWSDUDPHWHUVWKHQ isc_dsql_execute()UHTXLUHVDQLQSXW
;64/'$WRGHVFULEHWKRVHSDUDPHWHUV,WGRHVQRWSURYLGHIRUDQRXWSXW;64/'$$FDOOWR
isc_dsql_execute()WKDWH[HFXWHVD6(/(&7VWDWHPHQWUHVXOWVLQWKHFUHDWLRQRIDOLVW
FRQWDLQLQJDOOWKHURZVRIGDWDWKDWDUHWKHUHVXOWRIH[HFXWLRQRIWKHVWDWHPHQW7RDFFHVV
WKHVHURZVFDOOisc_dsql_fetch()LQDORRS(DFKFDOOWRisc_dsql_fetch()IHWFKHVWKHQH[W
URZIURPWKHVHOHFWOLVW
,IWKHVWDWHPHQWWREHH[HFXWHGUHTXLUHVLQSXWSDUDPHWHUYDOXHV WKDWLVLILWFRQWDLQV
SDUDPHWHUPDUNHUV WKHVHYDOXHVPXVWEHVXSSOLHGLQWKHLQSXW;64/'$[VTOGDEHIRUHFDOOLQJ
isc_dsql_execute()

API GUIDE 247

 CHAPTER 12 API FUNCTION REFERENCE

Note 7RH[HFXWHDVWDWHPHQWUHSHDWHGO\ZKHQLWERWKKDVLQSXWSDUDPHWHUVDQGUHWXUQYDOXHV
VXFKDV(;(&87(352&('85(XVHisc_dsql_execute2()ZKLFKUHTXLUHVERWKDQLQSXWDQG
DQRXWSXW;64/'$
,I\RXRQO\QHHGWRH[HFXWHDVWDWHPHQWRQFHDQGLWGRHVQRWUHWXUQDQ\GDWDFDOO
isc_dsql_execute_immediate()LQVWHDGRI isc_dsql_prepare()DQGisc_dsql_execute()
7RH[HFXWHDVWDWHPHQWZLWKERWKLQSXWDQGRXWSXWSDUDPHWHUVDVLQJOHWLPHXVH
isc_dsql_exec_immed2()
Note &5($7('$7$%$6(DQG6(775$16$&7,21FDQQRWEHH[HFXWHGZLWK
isc_dsql_execute()RUisc_dsql_execute2()7RH[HFXWHWKHVHVWDWHPHQWVXVH
isc_dsql_execute_immediate()

([DPSOH 7KHIROORZLQJSURJUDPIUDJPHQWLOOXVWUDWHVFDOOVWRisc_dsql_execute()DQG
isc_dsql_fetch(),WDOORFDWHVLQSXWDQGRXWSXW;64/'$VSUHSDUHVD6(/(&7VWDWHPHQW
H[HFXWHVLWDQGIHWFKHVDQGSURFHVVHVHDFKURZRQHE\RQH
#include <ibase.h>
ISC_STATUS status_vector[20], fetch_stat;
XSQLDA *isqlda, *osqlda;
XSQLVAR *ivar, *ovar;
char *str = "SELECT CITY, POPULATION FROM CITIES WHERE STATE = ?";
char *state = "CA";
/* Allocate an output XSQLDA osqlda. */
osqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(2);
osqlda->version = SQLDA_VERSION1;
osqlda->sqln = 2;

/* Prepare the statement, including filling in osqlda with information

about the select-list items to be returned by the statement. */
isc_dsql_prepare(
status_vector,
&tr_handle, /* Set in previous isc_start_transaction() call. */
&stmt_handle,
/* Allocated previously by isc_dsql_allocate_statement()
or isc_dsql_alloc_statement2() call. */
0,
str,
1,
osqlda);
if (status_vector[0] == 1 && status_vector[1])
{
/* Process error. */
isc_print_status(status_vector);
return(1);

248 INTERBASE 5
USING FUNCTION DEFINITIONS

/* Check to see whether or not the output XSQLDA had enough XSQLVARS
allocated. If not, correct it -- see isc_dsql_describe(). */

/* Allocate and fill in the input XSQLDA. This example assumes you know
how many input parameters there are (1), and all other information
necessary to supply a value. If this is not true, you will need to call
isc_dsql_describe_bind(). */
isqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(1));
isqlda->version = SQLDA_VERSION1;
isqlda->sqln = 1;
isqlda->sqld = 1;
ivar = isqlda->sqlvar[0];
ivar->sqltype = SQL_TEXT;
ivar->sqllen = sizeof(state);
ivar->sqldata = state;

/* Execute the statement. */

isc_dsql_execute(
status_vector,
&tr_handle, /* Set in previous isc_start_transaction() call. */
&stmt_handle,
/* Allocated previously by isc_dsql_allocate_statement()
or isc_dsql_alloc_statement2() call. */
1,
isqlda);
if (status_vector[0] == 1 && status_vector[1])
{
/* Process error. */
isc_print_status(status_vector);
return(1);
}

/* Set up an output XSQLVAR structure to allocate space for each item to

be returned. */
for (i=0, ovar = osqlda->sqlvar; i < osqlda->sqld; i++, ovar++)
{
dtype = (ovar->sqltype & ~1) /* Drop NULL bit for now. */
switch(dtype)
{
case SQL_TEXT:
ovar->sqldata = (char *)malloc(sizeof(char) * ovar->sqllen);
break;

API GUIDE 249

 CHAPTER 12 API FUNCTION REFERENCE

case SQL_LONG:
ovar->sqldata = (char *)malloc(sizeof(long));
/* Process remaining types. */
. . .
}
if (ovar->sqltype & 1)
{
/* Assign a variable to hold NULL status. */
ovar->sqlind = (short *)malloc(sizeof(short));
}
} /* end of for loop */

/* Fetch and process the rows in the select list one by one. */
while ((fetch_stat = isc_dsql_fetch(
status_vector,
&stmt_handle,
1,
osqlda)) == 0)
{
for (i=0; i < osqlda->sqld; i++)
{
/* Call a function you’ve written to process each returned
select-list item. */
process_column(osqlda->sqlvar[i]);
}
}

5HWXUQ9DOXH isc_dsql_execute()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHVVXFFHVV
$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKHVWDWXV
YHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRLVFBEDGBVWPWBKDQGOHLVFBEDGBWUDQVBKDQGOHRU
DQRWKHU,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_dsql_describe_bind()
isc_dsql_exec_immed2()isc_dsql_execute_immediate()
isc_dsql_execute2()isc_dsql_fetch()isc_dsql_prepare()
)RUPRUHLQIRUPDWLRQDERXWFUHDWLQJDQGSRSXODWLQJWKH;64/'$VHH´8QGHUVWDQGLQJWKH
;64/'$µRQSDJH 

250 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_dsql_execute2()
([HFXWHVDSUHYLRXVO\SUHSDUHG'64/VWDWHPHQW

6\QWD[ ISC_STATUS isc_dsql_execute2(

ISC_STATUS *status_vector,
isc_tr_handle *trans_handle,
isc_stmt_handle *stmt_handle,
unsigned short dialect,
XSQLDA *in_xsqlda,
XSQLDA *out_xsqlda);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
trans_handle isc_tr_handle * Pointer to a transaction handle whose value has been set by a
previous isc_start_transaction() call; trans_handle returns
an error if NULL
stmt_handle isc_stmt_handle * Pointer to a statement handle previously allocated with
isc_dsql_allocate_statement() or
isc_dsql_alloc_statement2(); the handle returns an error
in status_vector if it is NULL
dialect unsigned short Indicates the version of the extended SQL descriptor area
(XSQLDA) passed to the function; set this value to 1
in_xsqlda XSQLDA * Pointer to an optional, previously allocated XSQLDA used for
input; if input parameters are not supplied, set this value to
NULL
out_xsqlda XSQLDA * Pointer to an optional, previously allocated XSQLDA used for
results of statement execution; if not required, set this value
to NULL

'HVFULSWLRQ isc_dsql_execute2()H[HFXWHVDSUHYLRXVO\SUHSDUHG'64/VWDWHPHQWWKDWKDVLQSXW
SDUDPHWHUVDQGUHWXUQVUHVXOWVVXFKDV(;(&87(352&('85(DQG6(/(&7
,IWKHVWDWHPHQWWRH[HFXWHUHTXLUHVLQSXWSDUDPHWHUYDOXHV WKDWLVLILWFRQWDLQVSDUDPHWHU
PDUNHUV WKHVHYDOXHVPXVWEHVXSSOLHGLQWKHLQSXW;64/'$LQB[VTOGDEHIRUHFDOOLQJ
isc_dsql_execute2()

API GUIDE 251

 CHAPTER 12 API FUNCTION REFERENCE

,IWKHVWDWHPHQWWRH[HFXWHUHWXUQVYDOXHVWKH\DUHSODFHGLQWKHVSHFLILHGRXWSXW;64/'$
RXWB[VTOGD,ID18//YDOXHLVVXSSOLHGIRUWKHRXWSXW;64/'$DQGWKHVWDWHPHQWUHWXUQV
YDOXHVWKH\DUHVWRUHGLQDQUHVXOWVHW7RDFFHVVWKHUHWXUQHGGDWDXVHisc_dsql_fetch()LQD
ORRS

7,3 ,I\RXMXVWZDQWWRH[HFXWHRQFHDVWDWHPHQWUHWXUQLQJMXVWRQHJURXSRIGDWDFDOO
isc_dsql_exec_immed2()LQVWHDGRIisc_dsql_prepare()DQGisc_dsql_execute2()
7RH[HFXWHDVWDWHPHQWWKDWGRHVQRWUHWXUQDQ\GDWDDVLQJOHWLPHFDOO
isc_dsql_execute_immediate() LQVWHDG
RI
isc_dsql_prepare() DQGisc_dsql_execute2()
Note &5($7('$7$%$6(DQG6(775$16$&7,21FDQQRWEHH[HFXWHGZLWK
isc_dsql_execute()RUisc_dsql_execute2()7RH[HFXWHWKHVHVWDWHPHQWVXVH
isc_dsql_execute_immediate()

([DPSOH 7KHIROORZLQJSURJUDPIUDJPHQWLOOXVWUDWHVDVHTXHQFHRIFDOOVWKDWDOORFDWHVDQLQSXW
;64/'$DQGORDGVYDOXHVLQWRLWDOORFDWHVDQRXWSXW;64/'$SUHSDUHVDQ(;(&87(
352&('85(VWDWHPHQWDOORFDWHVVSDFHLQWKHRXWSXW;64/'$IRUHDFKFROXPQUHWXUQHGIRU
HDFKURZUHWULHYHGE\WKHFDOODQGH[HFXWHVWKHSUHSDUHGVWDWHPHQWSODFLQJUHWXUQYDOXHVLQ
WKHRXWSXW;64/'$
#include <ibase.h>
ISC_STATUS status_vector[20];
XSQLDA *isqlda, *osqlda;
XSQLVAR *ivar, *ovar;
short null_flag;
char *str = "EXECUTE PROCEDURE P1";
char *state = "CA";
/* Allocate an output XSQLDA osqlda. This example assumes you know that P1
will return one value. */
osqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(1);
osqlda->version = SQLDA_VERSION1;
osqlda->sqln = 1;

/* Prepare the statement, including filling in osqlda with information

about the item to be returned by the statement (procedure). */
isc_dsql_prepare(
status_vector,
&tr_handle, /* Set in previous isc_start_transaction() call. */
&stmt_handle,
/* Allocated previously by isc_dsql_allocate_statement()
or isc_dsql_alloc_statement2() call. */
0,
str,
1,

252 INTERBASE 5
USING FUNCTION DEFINITIONS

osqlda);
if (status_vector[0] == 1 && status_vector[1])
{
/* Process error. */
isc_print_status(status_vector);
return(1);
}
/* Set up the output XSQLVAR structure to allocate space for the return
value. Again, this example assumes you know that P1 returns just one value.
For an example of what to do if you’re not sure, see isc_dsql_describe().
For an example of setting up an output XSQLVAR structure to allocate space
for multiple return items, see the isc_dsql_execute() example program. */
ovar = osqlda->sqlvar[0];
dtype = (ovar->sqltype & ~1); /* Drop NULL bit for now. */
switch(dtype)
{
case SQL_TEXT:
ovar->sqldata = (char *)malloc(sizeof(char) * ovar->sqllen);
break;
case SQL_LONG:
ovar->sqldata = (char *)malloc(sizeof(long));
/* Process remaining types. */
. . .
}
if (ovar->sqltype & 1)
{
/* Assign a variable to hold NULL status. */
ovar->sqlind = &null_flag;
}
/* Allocate and fill in the input XSQLDA. This example assumes you know
how many input parameters there are (1), and all other information
necessary to supply a value. If this is not true, you will need to call
isc_dsql_describe_bind(). */
isqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(1);
isqlda->version = SQLDA_VERSION1;
isqlda->sqln = 1;
isqlda->sqld = 1;
ivar = isqlda->sqlvar[0];
ivar->sqltype = SQL_TEXT;
ivar->sqllen = sizeof(state);
ivar->sqldata = state;

/* Execute the statement. */

isc_dsql_execute2(

API GUIDE 253

 CHAPTER 12 API FUNCTION REFERENCE

status_vector,
&tr_handle, /* Set in previous isc_start_transaction() call. */
&stmt_handle,
/* Allocated previously by isc_dsql_allocate_statement()
or isc_dsql_alloc_statement2() call. */
1,
isqlda,
osqlda);
if (status_vector[0] == 1 && status_vector[1])
{
/* Process error. */
isc_print_status(status_vector);
return(1);
}
/* Now process the value returned in osqlda->sqlvar[0]. */
. . .

5HWXUQ9DOXH isc_dsql_execute2()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRLVFBEDGBVWPWBKDQGOH
LVFBEDGBWUDQVBKDQGOHRUDQRWKHU,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_dsql_exec_immed2()isc_dsql_execute_immediate()isc_dsql_execute()
isc_dsql_fetch()isc_dsql_prepare()
)RUPRUHLQIRUPDWLRQDERXWFUHDWLQJDQGSRSXODWLQJWKH;64/'$VHH´8QGHUVWDQGLQJWKH
;64/'$µRQSDJH 

254 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_dsql_execute_immediate()
3UHSDUHVDQGH[HFXWHVMXVWRQFHD'64/VWDWHPHQWWKDWGRHVQRWUHWXUQGDWD

6\QWD[ ISC_STATUS isc_dsql_execute_immediate(

ISC_STATUS *status_vector,
isc_db_handle *db_handle,
isc_tr_handle *trans_handle,
unsigned short length,
char *statement,
unsigned short dialect,
XSQLDA *xsqlda);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
db_handle isc_db_handle * Pointer to a database handle set by a previous call to
isc_attach_database()
db_handle returns an error in status_vector if it is NULL
trans_handle isc_tr_handle * Pointer to a transaction handle whose value has been set by a
previous isc_start_transaction() call; trans_handle returns
an error if NULL
length unsigned short Length of the DSQL statement in bytes; set to 0 in C programs
to indicate a null-terminated string
statement char * DSQL string to be executed
dialect unsigned short Indicates the version of the extended SQL descriptor area
(XSQLDA) passed to the function; set this
value to 1
xsqlda XSQLDA * Pointer to an optional, previously allocated XSQLDA used for
input; if input parameters are not supplied, set this value to
NULL

'HVFULSWLRQ isc_dsql_execute_immediate()SUHSDUHVWKH'64/VWDWHPHQWVSHFLILHGLQVWDWHPHQW
H[HFXWHVLWRQFHDQGGLVFDUGVLW7KHVWDWHPHQWPXVWQRWEHRQHWKDWUHWXUQVGDWD WKDWLVLW
PXVWQRWEHD6(/(&7RU(;(&87(352&('85(VWDWHPHQW 
,IVWDWHPHQWUHTXLUHVLQSXWSDUDPHWHUYDOXHV WKDWLVLILWFRQWDLQVSDUDPHWHUPDUNHUV WKHVH
YDOXHVPXVWEHVXSSOLHGLQWKHLQSXW;64/'$[VTOGD

API GUIDE 255

 CHAPTER 12 API FUNCTION REFERENCE

7,3 ,IVWDWHPHQWUHWXUQVGDWDRULILWQHHGVWREHH[HFXWHGPRUHWKDQRQFHXVH
isc_dsql_prepare()DQGisc_dsql_execute() RUisc_dsql_execute2() LQVWHDGRI
isc_dsql_execute_immediate()
Note <RXPXVWFDOOisc_dsql_execute_immediate()IRU&5($7('$7$%$6(DQG6(7
75$16$&7,21\RXFDQQRWSUHSDUHDQGH[HFXWHVXFKVWDWHPHQWVE\FDOOLQJ
isc_dsql_prepare()DQGisc_dsql_execute()

([DPSOH 7KHIROORZLQJSURJUDPIUDJPHQWFDOOVisc_dsql_execute_immediate()
#include <ibase.h>
ISC_STATUS status_vector[20];
char *insert_stmt =
"INSERT INTO CUSTOMER(CUSTNAME, BAL, CUSTNO)
VALUES("John Smith", 299.0, 5050)";

isc_dsql_execute_immediate(
status_vector,
&database_handle, /* Set in previous isc_attach_database() call. */
&tr_handle, /* Set in previous isc_start_transaction() call. */
0,
insert_stmt,
1,
NULL);
if (status_vector[0] == 1 && status_vector[1])
{
/* Process error. */
isc_print_status(status_vector);
return(1);
}

5HWXUQ9DOXH isc_dsql_execute_immediate()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HUR
LQGLFDWHVVXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQW
RIWKHVWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRLVFBEDGBGEBKDQGOH
LVFBEDGBWUDQVBKDQGOHRUDQRWKHU,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_dsql_exec_immed2()isc_dsql_execute()isc_dsql_prepare()
)RUPRUHLQIRUPDWLRQDERXWFUHDWLQJDQGSRSXODWLQJWKH;64/'$VHH´8QGHUVWDQGLQJWKH
;64/'$µRQSDJH 

256 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_dsql_exec_immed2()
3UHSDUHVDQGH[HFXWHVMXVWRQFHD'64/VWDWHPHQWWKDWUHWXUQVQRPRUHWKDQRQHURZRI
GDWD

6\QWD[ ISC_STATUS isc_dsql_exec_immed2(

ISC_STATUS *status_vector,
isc_db_handle *db_handle,
isc_tr_handle *trans_handle,
unsigned short length,
char *statement,
unsigned short dialect,
XSQLDA *in_xsqlda,
XSQLDA *out_xsqlda);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
db_handle isc_db_handle * Pointer to a database handle set by a previous call to
isc_attach_database()
db_handle returns an error in status_vector if it is NULL
trans_handle isc_tr_handle * Pointer to a transaction handle whose value has been set by a
previous isc_start_transaction() call; trans_handle returns
an error if NULL
length unsigned short Length of the DSQL statement, in bytes; set to 0 in C programs
to indicate a null-terminated string
statement char * DSQL string to be executed
dialect unsigned short Indicates the version of the extended SQL descriptor area
(XSQLDA) passed to the function; set this value to 1
in_xsqlda XSQLDA * Pointer to an optional, previously allocated XSQLDA used for
input; if input parameters are not supplied, set this value to
NULL
out_xsqlda XSQLDA * Pointer to an optional, previously allocated XSQLDA used for
results of statement execution. If not required, set this value to
NULL.

API GUIDE 257

 CHAPTER 12 API FUNCTION REFERENCE

'HVFULSWLRQ isc_dsql_exec_immed2()SUHSDUHVWKH'64/VWDWHPHQWVSHFLILHGLQVWDWHPHQWH[HFXWHVLW
RQFHDQGGLVFDUGVLWVWDWHPHQWFDQUHWXUQDVLQJOHVHWRIYDOXHV LHLWFDQEHDQ(;(&87(
352&('85(RUVLQJOHWRQ6(/(&7 LQWKHRXWSXW;64/'$
,IVWDWHPHQWUHTXLUHVLQSXWSDUDPHWHUYDOXHV WKDWLVLILWFRQWDLQVSDUDPHWHUPDUNHUV WKHVH
YDOXHVPXVWEHVXSSOLHGLQWKHLQSXW;64/'$LQB[VTOGD
)RUVWDWHPHQWVWKDWUHWXUQPXOWLSOHURZVRIGDWDXVHisc_dsql_prepare()
isc_dsql_execute2()DQGisc_dsql_fetch()

([DPSOH 7KHIROORZLQJSURJUDPIUDJPHQWFDOOVisc_dsql_exec_immed2()
ISC_STATUS status_vector[20];
XSQLDA *in_xsqlda, *out_xsqlda;
char *execute_p1 = "EXECUTE PROCEDURE P1 ?";
/* Set up input and output XSQLDA structures here. */
. . .
isc_dsql_exec_immed2(
status_vector,
&database_handle, /* Set in previous isc_attach_database() call. */
&tr_handle, /* Set in previous isc_start_transaction() call. */
0,
execute_p1,
1,
in_xsqlda,
out_xsqlda);
if (status_vector[0] == 1 && status_vector[1])
{
/* Process error. */
isc_print_status(status_vector);
return(1);
}

5HWXUQ9DOXH isc_dsql_exec_immed2()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRLVFBEDGBGEBKDQGOH
LVFBEDGBWUDQVBKDQGOHRUDQRWKHU,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_dsql_execute2()isc_dsql_prepare()
)RUPRUHLQIRUPDWLRQDERXWFUHDWLQJDQGSRSXODWLQJWKH;64/'$VHH´8QGHUVWDQGLQJWKH
;64/'$µRQSDJH 

258 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_dsql_fetch()
5HWULHYHVGDWDUHWXUQHGE\DSUHYLRXVO\SUHSDUHGDQGH[HFXWHG'64/VWDWHPHQW

6\QWD[ ISC_STATUS isc_dsql_fetch(

ISC_STATUS *status_vector,
isc_stmt_handle *stmt_handle,
unsigned short dialect,
XSQLDA *xsqlda);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
stmt_handle isc_stmt_handle * Pointer to a statement handle previously allocated with
isc_dsql_allocate_statement() or
isc_dsql_alloc_statement2(); the handle returns an error
in status_vector if it is NULL
dialect unsigned short Indicates the version of the extended SQL descriptor area
(XSQLDA) passed to the function; set this value to 1
xsqlda XSQLDA * Pointer to an optional, previously allocated XSQLDA used for
results of statement execution

'HVFULSWLRQ isc_dsql_fetch()UHWULHYHVRQHURZRIGDWDLQWR[VTOGDHDFKWLPHLWLVFDOOHG,WLVXVHGLQD
ORRSWRUHWULHYHDQGSURFHVVHDFKURZRIGDWDIRUVWDWHPHQWVWKDWUHWXUQPXOWLSOHURZVLQD
FXUVRU
$FXUVRULVDRQHZD\SRLQWHULQWRWKHRUGHUHGVHWRIURZVUHWULHYHGE\DVWDWHPHQW$FXUVRU
LVRQO\QHHGHGWRSURFHVVSRVLWLRQHG83'$7(DQG'(/(7(VWDWHPHQWVPDGHDJDLQVWWKHURZV
UHWULHYHGE\isc_dsql_fetch()IRU6(/(&7VWDWHPHQWVWKDWVSHFLI\DQRSWLRQDO)2583'$7(
2)FODXVH
,WLVXSWRWKHDSSOLFDWLRQWRSURYLGHWKHORRSFRQVWUXFWIRUIHWFKLQJWKHGDWD
%HIRUHFDOOLQJisc_dsql_fetch()DVWDWHPHQWPXVWEHSUHSDUHGZLWK isc_dsql_prepare()
DQGH[HFXWHGZLWKisc_dsql_execute() RU isc_dsql_execute2()ZLWKD18//RXWSXW
;64/'$DUJXPHQW 6WDWHPHQWH[HFXWLRQSURGXFHVDUHVXOWVHWFRQWDLQLQJWKHGDWDUHWXUQHG
(DFKFDOOWRisc_dsql_fetch()UHWULHYHVWKHQH[WDYDLODEOHURZRIGDWDIURPWKHUHVXOWVHWLQWR
[VTOGD

API GUIDE 259

 CHAPTER 12 API FUNCTION REFERENCE

([DPSOH 7KHIROORZLQJSURJUDPIUDJPHQWLOOXVWUDWHVDVHTXHQFHRIFDOOVWKDWDOORFDWHVDQRXWSXW
;64/'$SUHSDUHVDVWDWHPHQWIRUH[HFXWLRQDOORFDWHVDQ;64/9$5VWUXFWXUHLQWKH
;64/'$IRUHDFKFROXPQRIGDWDWREHUHWULHYHGH[HFXWHVWKHVWDWHPHQWSURGXFLQJDVHOHFW
OLVWRIUHWXUQHGGDWDWKHQIHWFKHVDQGSURFHVVHVHDFKURZLQDORRS
#include <ibase.h>
#define LASTLEN 20
#define FIRSTLEN 15
#define EXTLEN 4
typedef struct vary {
short vary_length;
char vary_string[1];
} VARY;
ISC_STATUS status_vector[20], retcode;
long SQLCODE;
XSQLDA *osqlda;
XSQLVAR *ovar;
short flag0, flag1, flag2;
char *str =
"SELECT last_name, first_name, phone_ext FROM phone_list
WHERE location = "Monterey" ORDER BY last_name, first_name";
char last_name[LASTLEN + 2];
char first_name[FIRSTLEN + 2];
char phone_ext[EXTLEN + 2];
VARY *vary;
/* Allocate an output XSQLDA osqlda. */
osqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(3);
osqlda->version = SQLDA_VERSION1;
osqlda->sqln = 3;
/* Prepare the statement. */
isc_dsql_prepare(
status_vector,
&tr_handle, /* Set in previous isc_start_transaction() call. */
&stmt_handle,
/* Allocated previously by isc_dsql_allocate_statement()
or isc_dsql_alloc_statement2() call. */
0,
str,
1,
osqlda);
if (status_vector[0] == 1 && status_vector[1])
{
/* Process error. */
isc_print_status(status_vector);

260 INTERBASE 5
USING FUNCTION DEFINITIONS

return(1);
}
/* Set up an output XSQLVAR structure to allocate space for each item to
be returned. */
osqlda->sqlvar[0].sqldata = last_name;
osqlda->sqlvar[0].sqltype = SQL_VARYING + 1;
osqlda->sqlvar[0].sqlind = &flag0;
osqlda->sqlvar[1].sqldata = first_name;
osqlda->sqlvar[1].sqltype = SQL_VARYING + 1;
osqlda->sqlvar[1].sqlind = &flag1;
osqlda->sqlvar[2].sqldata = phone_ext;
osqlda->sqlvar[2].sqltype = SQL_VARYING + 1;
osqlda->sqlvar[2].sqlind = &flag2;
/* Execute the statement. */
isc_dsql_execute(
status_vector,
&tr_handle, /* Set in previous isc_start_transaction() call. */
&stmt_handle,
/* Allocated previously by isc_dsql_allocate_statement()
or isc_dsql_alloc_statement2() call. */
1,
NULL);
if (status_vector[0] == 1 && status_vector[1])
{
/* Process error. */
isc_print_status(status_vector);
return(1);
}

printf("\n%-20s %-15s %-10s\n\n", "LAST NAME", "FIRST NAME", "EXTENSION");

/* Fetch and print the records in the select list one by one. */
while ((retcode = isc_dsql_fetch(
status_vector,
&stmt_handle,
1,
osqlda)) == 0)
{
vary = (VARY *)last_name;
printf("%-20.*s ", vary->vary_length, vary->vary_string);
vary = (VARY *)first_name;
printf("%-15.*s ", vary->vary_length, vary->vary_string);
vary = (VARY *)phone_ext;
printf("%-4.*s ", vary->vary_length, vary->vary_string);
}

API GUIDE 261

 CHAPTER 12 API FUNCTION REFERENCE

if (retcode != 100L)
{
SQLCODE = isc_sqlcode(status_vector);
isc_print_sqlerror(SQLCODE, status_vector);
return(1);
}

5HWXUQ9DOXH isc_dsql_fetch()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHVVXFFHVV
7KHYDOXHLQGLFDWHVWKDWQRPRUHURZVUHPDLQWREHUHWULHYHG$Q\RWKHUQRQ]HURYDOXH
LQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKHVWDWXVYHFWRULVVHWWRDQG
WKHVHFRQGHOHPHQWLVVHWWRLVFBEDGBVWPWBKDQGOHRUDQRWKHU,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_dsql_execute()isc_dsql_execute2()isc_dsql_prepare()

isc_dsql_free_statement()
)UHHVDVWDWHPHQWKDQGOHDQGDOOUHVRXUFHVDOORFDWHGIRULWRUFORVHVDFXUVRUDVVRFLDWHGZLWK
WKHVWDWHPHQWUHIHUHQFHGE\DVWDWHPHQWKDQGOH

6\QWD[ ISC_STATUS isc_dsql_free_statement(

ISC_STATUS *status_vector,
isc_stmt_handle *stmt_handle,
unsigned short option);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
stmt_handle isc_stmt_handle * Pointer to a statement handle previously allocated with
isc_dsql_allocate_statement() or
isc_dsql_alloc_statement2(); the handle returns an error
in status_vector if it is NULL
option unsigned short Either DSQL_close or DSQL_drop

'HVFULSWLRQ isc_dsql_free_statement()HLWKHUIUHHVDVWDWHPHQWKDQGOHDQGDOOUHVRXUFHVDOORFDWHGIRULW
RSWLRQ '64/BGURS RUFORVHVDFXUVRUDVVRFLDWHGZLWKWKHVWDWHPHQW RSWLRQ 
'64/BFORVH 

262 INTERBASE 5
USING FUNCTION DEFINITIONS

Note isc_dsql_free_statement()GRHVQRWKLQJLILWLVFDOOHGZLWKDQRSWLRQYDOXHRWKHUWKDQ
'64/BGURSRU'64/BFORVH

4 '64/BFORVH
&DOOisc_dsql_free_statement()ZLWKWKH'64/BFORVHRSWLRQWRFORVHDFXUVRUDIWHULWLVQR
ORQJHUQHHGHGWKDWLVDIWHUIHWFKLQJDQGSURFHVVLQJDOOWKHURZVUHVXOWLQJIURPWKHH[HFXWLRQ
RIDTXHU\$FXUVRUQHHGRQO\EHFORVHGLQWKLVPDQQHULILWZDVSUHYLRXVO\RSHQHGDQG
DVVRFLDWHGZLWKVWPWBKDQGOHE\ isc_dsql_set_cursor_name()
'64/BFORVHFORVHVDFXUVRUEXWWKHVWDWHPHQWLWZDVDVVRFLDWHGZLWKUHPDLQVDYDLODEOHIRU
IXUWKHUH[HFXWLRQ
,I\RXKDYHXVHGDFXUVRUWRSHUIRUPXSGDWHVRUGHOHWHVRQDOOWKHURZVUHWXUQHGIURPWKH
H[HFXWLRQRIDTXHU\DQG\RXZDQWWRSHUIRUPRWKHUXSGDWHRUGHOHWHRSHUDWLRQVRQURZV
UHVXOWLQJIURPH[HFXWLRQRIWKHVDPHVWDWHPHQWDJDLQ SRVVLEO\ZLWKGLIIHUHQWLQSXW
SDUDPHWHUV IROORZWKHVHVWHSV
 &ORVHWKHFXUVRUZLWKisc_dsql_free_statement()
 5HRSHQLWZLWKisc_dsql_set_cursor_name()
 ,IGHVLUHGFKDQJHWKHLQSXWSDUDPHWHUVWREHSDVVHGWRWKHVWDWHPHQW
 5HH[HFXWHWKHVWDWHPHQWWRUHWULHYHDQHZVHOHFWOLVW
 5HWULHYHURZVLQDORRSZLWKisc_dsql_fetch()DQGSURFHVVWKHPDJDLQZLWK
isc_dsql_execute_immediate()

4 '64/BGURS
6WDWHPHQWKDQGOHVDOORFDWHGZLWKisc_dsql_allocate_statement() PXVWEHUHOHDVHGZKHQQR
ORQJHUQHHGHGE\FDOOLQJisc_dsql_free_statement()ZLWKWKH'64/BGURSRSWLRQ7KLV
RSWLRQIUHHVDOOUHVRXUFHVDVVRFLDWHGZLWKWKHVWDWHPHQWKDQGOHDQGFORVHVDQ\RSHQFXUVRUV
DVVRFLDWHGZLWKWKHVWDWHPHQWKDQGOH

([DPSOH 7KHIROORZLQJSURJUDPIUDJPHQWVKRZVH[DPSOHVRIWKHWZRW\SHVRI
isc_dsql_free_statement()FDOOV,WDVVXPHVWKDWVWPWBKDQGOHDQGVWPWBKDQGOHDUH
VWDWHPHQWKDQGOHVHDFKRIZKLFKZDVSUHYLRXVO\DOORFDWHGZLWKHLWKHU
isc_dsql_allocate_statement()RUisc_dsql_alloc_statement2()$FXUVRULVDOVR
DVVXPHGWRKDYHEHHQDVVRFLDWHGZLWKWKHVWDWHPHQWUHIHUHQFHGE\VWPWBKDQGOH
#include <ibase.h>
ISC_STATUS status_vector[20];
. . .
/* Free the cursor associated with stmt_handle1. */
isc_dsql_free_statement(
status_vector,

API GUIDE 263

 CHAPTER 12 API FUNCTION REFERENCE

&stmt_handle1,
DSQL_close);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector);
return(1);
}
/* Free stmt_handle2. */
isc_dsql_free_statement(
status_vector,
&stmt_handle2,
DSQL_drop);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector);
return(1);
}

5HWXUQ9DOXH isc_dsql_free_statement()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRLVFBEDGBVWPWBKDQGOHRUDQRWKHU
,QWHU%DVHHUURUFRGH7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKH
VWDWXVYHFWRUGLUHFWO\)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU
´+DQGOLQJ(UURU&RQGLWLRQVµ

6HH$OVR isc_dsql_allocate_statement()isc_dsql_alloc_statement2()
isc_dsql_set_cursor_name()

264 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_dsql_prepare()
3UHSDUHVD'64/VWDWHPHQWIRUUHSHDWHGH[HFXWLRQ

6\QWD[ ISC_STATUS isc_dsql_prepare(

ISC_STATUS *status_vector,
isc_tr_handle *trans_handle,
isc_stmt_handle *stmt_handle,
unsigned short length,
char *statement,
unsigned short dialect,
XSQLDA *xsqlda);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
trans_handle isc_tr_handle * Pointer to a transaction handle whose value has been set by a
previous isc_start_transaction() call; trans_handle returns
an error if NULL
stmt_handle isc_stmt_handle * Pointer to a statement handle previously allocated with
isc_dsql_allocate_statement() or
isc_dsql_alloc_statement2(); the handle returns an error
in status_vector if it is NULL
length unsigned short Length of the DSQL statement, in bytes; set to 0 in C programs
to indicate a null-terminated string
statement char * DSQL string to be executed
dialect unsigned short Indicates the version of the extended SQL descriptor area
(XSQLDA) passed to the function; set this value to 1
xsqlda XSQLDA * Pointer to an optional, previously allocated XSQLDA used for
results of statement execution

'HVFULSWLRQ isc_dsql_prepare()UHDGLHVWKH'64/VWDWHPHQWVSHFLILHGLQVWDWHPHQWIRUUHSHDWHG
H[HFXWLRQE\FKHFNLQJLWIRUV\QWD[HUURUVDQGSDUVLQJLWLQWRDIRUPDWWKDWFDQEHHIILFLHQWO\
H[HFXWHG$OO6(/(&7VWDWHPHQWVPXVWEHSUHSDUHGZLWKisc_dsql_prepare()
$IWHUDVWDWHPHQWLVSUHSDUHGLWLVDYDLODEOHIRUH[HFXWLRQDVPDQ\WLPHVDVQHFHVVDU\GXULQJ
WKHFXUUHQWVHVVLRQ3UHSDULQJDVWDWHPHQWIRUUHSHDWHGH[HFXWLRQLVPRUHHIILFLHQWWKDQXVLQJ
isc_dsql_execute_immediate()RU isc_dsql_exec_immed2()RYHUDQGRYHUDJDLQWR
SUHSDUHDQGH[HFXWHDVWDWHPHQW

API GUIDE 265

 CHAPTER 12 API FUNCTION REFERENCE

,IDVWDWHPHQWWREHSUHSDUHGGRHVQRWUHWXUQGDWDVHWWKHRXWSXW;64/'$WR18//
2WKHUZLVHWKHRXWSXW;64/'$PXVWEHDOORFDWHGSULRUWRFDOOLQJisc_dsql_prepare()
$OORFDWHWKH;64/'$XVLQJWKHPDFUR;64/'$B/(1*7+GHILQHGLQLEDVHKDVIROORZV
xsqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(n));

;64/'$B/(1*7+FDOFXODWHVWKHQXPEHURIE\WHVUHTXLUHGZKHQQUHVXOWFROXPQVZLOOEH
UHWXUQHGE\WKHVWDWHPHQWDQGDOORFDWHVWKHDSSURSULDWHDPRXQWRIVWRUDJH
$IWHUDOORFDWLQJWKH;64/'$[VTOGDVHW[VTOGD!YHUVLRQWR64/'$B9(56,21DQGVHW
[VTOGDBVTOQWRLQGLFDWHWKHQXPEHURI;64/9$5VWUXFWXUHVDOORFDWHG
:KHQisc_dsql_prepare()LVFDOOHGLWILOOVLQWKHRWKHUILHOGVRIWKH;64/'$DQGDOOWKH
;64/9$5VZLWKLQIRUPDWLRQVXFKDVWKHGDWDW\SHOHQJWKDQGQDPHRIWKHFRUUHVSRQGLQJ
VHOHFWOLVWLWHPVLQWKHVWDWHPHQW,WILOOVLQ[VTOGD!VTOGZLWKWKHDFWXDOQXPEHURIVHOHFWOLVW
LWHPVUHWXUQHG,I[VTOGD!VTOGLVJUHDWHUWKDQ[VTOGD!VTOQWKHQHQRXJKURRPLVQRWDOORFDWHG
DQGWKH;64/'$PXVWEHUHVL]HGE\IROORZLQJWKHVHVWHSV
 5HFRUGWKHFXUUHQWYDOXHRIWKH[VTOGD!VTOG
 )UHHWKHVWRUDJHSUHYLRXVO\DOORFDWHGIRU[VTOGD
 5HDOORFDWHVWRUDJHIRU[VTOGDWKLVWLPHVSHFLI\LQJWKHFRUUHFWQXPEHU IURPVWHS
 LQWKHDUJXPHQWWR;64/'$B/(1*7+
 5HVHW[VTOGD!VTOGDQG[VTOGD!YHUVLRQ
 ([HFXWHisc_dsql_describe()WRILOOLQWKH[VTOGDILHOGV
Note ,IWKHSUHSDUHGVWDWHPHQWUHTXLUHVLQSXWSDUDPHWHUYDOXHVWKHQDQLQSXW;64/'$ZLOO
QHHGWREHDOORFDWHGDQGILOOHGLQZLWKDSSURSULDWHYDOXHVSULRUWRFDOOLQJisc_dsql_execute()
RUisc_dsql_execute2()<RXFDQHLWKHUDOORFDWHDQGGLUHFWO\ILOOLQDOOWKHILHOGVRIWKHLQSXW
;64/'$RU\RXFDQDOORFDWHLWFDOOisc_dsql_describe_bind()WRJHWLQIRUPDWLRQUHJDUGLQJ
WKHQXPEHUDQGW\SHVRISDUDPHWHUVUHTXLUHGWKHQILOOLQDSSURSULDWHYDOXHV

([DPSOH 7KHIROORZLQJSURJUDPIUDJPHQWLOOXVWUDWHVWKHDOORFDWLRQRIWKHRXWSXW;64/'$DQGDFDOO
WRisc_dsql_prepare()
#include <ibase.h>
ISC_STATUS status_vector[20];
XSQLDA *osqlda;
char *query =
"SELECT CITY, STATE, POPULATION FROM CITIES \
WHERE STATE = "NY" ORDER BY CITY DESCENDING";

osqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(3);

osqlda->version = SQLDA_VERSION1;
osqlda->sqln = 3;

266 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_dsql_prepare(
status_vector,
&tr_handle, /* Set in previous isc_start_transaction() call. */
&stmt_handle,
/* Allocated previously by isc_dsql_allocate_statement()
or isc_dsql_alloc_statement2() call. */
0,
query,
1,
osqlda);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector);
return(1);
}

0RUHFRPSOHWHH[DPSOHVVKRZLQJWKHVXEVHTXHQWH[HFXWLRQDQGIHWFKLQJRIUHVXOWGDWDDUH
SURYLGHGLQWKHH[DPSOHSURJUDPVIRUisc_dsql_execute()isc_dsql_execute2()DQG
isc_dsql_fetch()

5HWXUQ9DOXH isc_dsql_prepare()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHVVXFFHVV
$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKHVWDWXV
YHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRLVFBEDGBVWPWBKDQGOHLVFBEDGBWUDQVBKDQGOHRU
DQRWKHU,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_dsql_describe()isc_dsql_describe_bind()isc_dsql_execute()
isc_dsql_execute2()isc_dsql_fetch()
)RUPRUHLQIRUPDWLRQDERXWFUHDWLQJDQGSRSXODWLQJWKH;64/'$VHH´8QGHUVWDQGLQJWKH
;64/'$µRQSDJH RI&KDSWHU´:RUNLQJZLWK'\QDPLF64/µ

API GUIDE 267

 CHAPTER 12 API FUNCTION REFERENCE

isc_dsql_set_cursor_name()
'HILQHVDFXUVRUQDPHDQGDVVRFLDWHVLWZLWKD'64/VWDWHPHQW

6\QWD[ ISC_STATUS isc_dsql_set_cursor_name(

ISC_STATUS *status_vector,
isc_stmt_handle *stmt_handle,
char *cursor_name,
unsigned short type);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
stmt_handle isc_stmt_handle * Pointer to a statement handle previously allocated with
isc_dsql_allocate_statement() or
isc_dsql_alloc_statement2(); the handle returns an error
in status_vector if it is NULL
cursor_name char * String name of a cursor
type unsigned short Reserved for future use; set to NULL

'HVFULSWLRQ isc_dsql_set_cursor_name()GHILQHVDFXUVRUQDPHDQGDVVRFLDWHVLWZLWKD'64/
VWDWHPHQWKDQGOHIRUDVWDWHPHQWWKDWUHWXUQVPXOWLSOHURZVRIGDWD IRUH[DPSOH6(/(&7 
HIIHFWLYHO\RSHQLQJWKHFXUVRUIRUDFFHVV
$FXUVRULVDRQHZD\SRLQWHULQWRWKHRUGHUHGVHWRIURZVUHWULHYHGE\DVWDWHPHQW$FXUVRU
LVRQO\QHHGHGWRSURFHVVSRVLWLRQHG83'$7(DQG'(/(7(VWDWHPHQWVPDGHDJDLQVWWKHURZV
UHWULHYHGE\isc_dsql_fetch()IRU6(/(&7VWDWHPHQWVWKDWVSHFLI\DQRSWLRQDO)2583'$7(
2)FODXVH
Note ,Q83'$7(RU'(/(7(VWDWHPHQWVWKHFXUVRUQDPHFDQQRWEHVXSSOLHGDVDSDUDPHWHU
PDUNHU " 
:KHQDFXUVRULVQRORQJHUQHHGHGFORVHLWZLWKWKH'64/BFORVHRSWLRQRI
isc_dsql_free_statement()

([DPSOH 7KHIROORZLQJSVHXGRFRGHLOOXVWUDWHVWKHFDOOLQJVHTXHQFHQHFHVVDU\WRH[HFXWHDQ83'$7(
RU'(/(7(ZLWKWKH:+(5(&855(172)FODXVHXVLQJDFXUVRUQDPHHVWDEOLVKHGDQG
RSHQHGZLWKisc_dsql_set_cursor_name()
#include <ibase.h>
ISC_STATUS status_vector[20], fetch_stat;
isc_stmt_handle st_handle = NULL;
char *cursor = "S";

268 INTERBASE 5
USING FUNCTION DEFINITIONS

/* Allocate the statement handle st_handle. */

isc_dsql_allocate_statement(
status_vector,
&db, /* Database handle set by isc_attach_database() call. /*
&st_handle);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector);
return(1);
}
/* Set up an output XSQLDA osqlda here. */
/* Call isc_dsql_prepare() to prepare the SELECT statement. */
/* Set up an input XSQLDA, if needed, for the SELECT statement. */
/* Call isc_dsql_execute() to execute the SELECT statement. */
/* Set up an input XSQLDA (if needed) for the UPDATE or DELETE statement. */
/* Declare the cursor name, and associate it with st_handle. */
isc_dsql_set_cursor_name(
status_vector,
&st_handle,
cursor, 0);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector);
return(1);
}
/* Fetch rows one by one, with the cursor pointing to each row as it is
fetched, and execute an UPDATE or DELETE statement to update or delete the
row pointed to by the cursor. */
while ((fetch_stat = isc_dsql_fetch(
status_vector, &st_handle, 1, osqlda)) == 0)
{
. . .
/* Update or delete the current row by executing an "UPDATE ...
WHERE CURRENT OF S" or "DELETE ... WHERE CURRENT OF S"
statement, where "S" is the name of the cursor declared in
isc_dsql_set_cursor_name(). */
}

5HWXUQ9DOXH isc_dsql_set_cursor_name()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HUR
LQGLFDWHVVXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQW
RIWKHVWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRLVFBEDGBVWPWBKDQGOHRU
DQRWKHU,QWHU%DVHHUURUFRGH

API GUIDE 269

 CHAPTER 12 API FUNCTION REFERENCE

7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_dsql_fetch()isc_dsql_free_statement()

isc_dsql_sql_info()
5HWXUQVUHTXHVWHGLQIRUPDWLRQDERXWDSUHSDUHG'64/VWDWHPHQW

6\QWD[ ISC_STATUS isc_dsql_sql_info(

ISC_STATUS *status_vector,
isc_stmt_handle *stmt_handle,
unsigned short item_length,
char *items,
unsigned short buffer_length,
char *buffer);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
stmt_handle isc_stmt_handle * Pointer to a statement handle previously allocated with
isc_dsql_allocate_statement() or
isc_dsql_alloc_statement2(); the handle returns an error
in status_vector if it is NULL
item_length unsigned short Number of bytes in the string of information items in items
items char * String of requested information items
buffer_length unsigned short Number of bytes in the result buffer, buffer
buffer char * User-provided buffer for holding returned data; must be large
enough to hold the information requested

'HVFULSWLRQ isc_dsql_sql_info()UHWXUQVUHTXHVWHGLQIRUPDWLRQDERXWDVWDWHPHQWSUHSDUHGZLWKDFDOO
WRisc_dsql_prepare()7KHPDLQDSSOLFDWLRQQHHGIRUWKLVIXQFWLRQLVWRGHWHUPLQHWKH
VWDWHPHQWW\SHRIDQXQNQRZQSUHSDUHGVWDWHPHQWIRUH[DPSOHDVWDWHPHQWHQWHUHGE\WKH
XVHUDWUXQWLPH
5HTXHVWHGLQIRUPDWLRQFDQLQFOXGHWKH
g 6WDWHPHQWW\SH

270 INTERBASE 5
USING FUNCTION DEFINITIONS

g 1XPEHURILQSXWSDUDPHWHUVUHTXLUHGE\WKHVWDWHPHQW
g 1XPEHURIRXWSXWYDOXHVUHWXUQHGE\WKHVWDWHPHQW
g 'HWDLOHGLQIRUPDWLRQUHJDUGLQJHDFKLQSXWSDUDPHWHURURXWSXWYDOXHLQFOXGLQJLWVGDWDW\SH
VFDOHDQGOHQJWK

([DPSOH 7KHIROORZLQJLOOXVWUDWHVDFDOOWRisc_dsql_sql_info()WRGHWHUPLQHWKHVWDWHPHQWW\SHRI
WKHVWDWHPHQWZKRVHKDQGOHLVUHIHUHQFHGE\VWPW
int statement_type;
int length;
char type_item[] = {isc_info_sql_stmt_type};
char res_buffer[8];
isc_dsql_sql_info(
status_vector,
&stmt,
/* Allocated previously by isc_dsql_allocate_statement() or
isc_dsql_alloc_statement2() call. */
sizeof(type_item),
type_item,
sizeof(res_buffer),
res_buffer);

if (res_buffer[0] == isc_info_sql_stmt_type)
{
length = isc_vax_integer(buffer[1], 2);
statement_type = isc_vax_integer(buffer[3], length);
}

5HWXUQ9DOXH isc_dsql_sql_info()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_dsql_describe_bind()isc_dsql_describe()isc_vax_integer()
)RUPRUHLQIRUPDWLRQDERXWGHWHUPLQLQJXQNQRZQVWDWHPHQWW\SHVDWUXQWLPHVHH
´'HWHUPLQLQJDQXQNQRZQVWDWHPHQWW\SHDWUXQWLPHµRQSDJH RI&KDSWHU´:RUNLQJ
ZLWK'\QDPLF64/µ

API GUIDE 271

 CHAPTER 12 API FUNCTION REFERENCE

isc_encode_date()
7UDQVODWHVDGDWHIURPWKH&WPIRUPDWWR,QWHU%DVH,6&B48$'IRUPDWSULRUWRLQVHUWLQJRU
XSGDWLQJD'$7(YDOXHLQDWDEOH

6\QWD[ void isc_encode_date(

void *tm_date,
ISC_QUAD *ib_date);

Parameter Type Description

tm_date void * Pointer to a C tm structure
ib_date ISC_QUAD * Pointer to an eight-byte ISC_QUAD structure containing a date in
InterBase format

'HVFULSWLRQ isc_encode_date()WUDQVODWHVDGDWHLQD&WLPHVWUXFWXUHLQWRDQ,6&B48$'IRUPDWLQWHUQDO
WR,QWHU%DVH7KLVFDOOLVXVHGSULRUWRZULWLQJ'$7(GDWDWRDWDEOHWRJXDUDQWHHWKDWWKHGDWH
LVLQDIRUPDWUHFRJQL]HGE\,QWHU%DVH
8VHWKHisc_dsqlIDPLO\RI$3,FDOOVWRLQVHUWRUXSGDWH'$7(GDWDIURPWKH,6&B48$'
VWUXFWXUHLQDWDEOH

([DPSOH 7KHIROORZLQJFRGHIUDJPHQWLOOXVWUDWHVGHFODULQJWLPHVWUXFWXUHVDQGFDOOLQJ
isc_encode_date()WRWUDQVODWHD&WLPHIRUPDWLQWRDQ,QWHU%DVHGDWHIRUPDWSULRUWR
LQVHUWLQJRUXSGDWLQJDWDEOH
#include <time.h>
#include <ibase.h>
. . .
struct tm hire_time;
ISC_QUAD hire_date;
. . .
/* Store date info into the tm struct here. */
. . .
isc_encode_date(&hire_time, &hire_date);
/* Now use a DSQL INSERT or UPDATE statement to move the date into a DATE
column. */

5HWXUQ9DOXH 1RQH

6HH$OVR isc_decode_date()

272 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_event_block()
$OORFDWHVWZRHYHQWSDUDPHWHUEXIIHUV (3%V IRUVXEVHTXHQWXVHZLWKRWKHU$3,HYHQWFDOOV

6\QWD[ long isc_event_block(

char **event_buffer,
char **result_buffer,
unsigned short id_count,
. . .);

Parameter Type Description

event_buffer char ** Address of a character pointer; this function allocates and
initializes an event parameter buffer and stores its address into
the character pointer
result_buffer char ** Address of a character pointer; this function allocates an event
parameter buffer, and stores its address into the character
pointer
id_count unsigned short Number of event identifier strings that follow
… char * Up to 15 null-terminated and comma-separated strings that
each name an event

'HVFULSWLRQ isc_event_block()PXVWEHFDOOHGEHIRUHDQ\RWKHUHYHQWIXQFWLRQV,W
g $OORFDWHVWZRHYHQWSDUDPHWHUEXIIHUVRIWKHVDPHVL]HDQGVWRUHVWKHLUDGGUHVVHVLQWRWKH
FKDUDFWHUSRLQWHUVDGGUHVVHGE\HYHQWBEXIIHUDQGUHVXOWBEXIIHU
g 6WRUHVLQWRWKHEXIIHUUHIHUHQFHGE\HYHQWBEXIIHUWKHQDPHVDQGHYHQWFRXQWVIRUHDFKRIWKH
VSHFLILHGHYHQWV7KHQDPHVDUHWKHRQHVWKDWDSSHDUDVWKHILQDODUJXPHQWVWR
isc_event_block()7KHHYHQWFRXQWVDUHLQLWLDOL]HGWR]HURDQGDUHXVHGWRVSHFLI\KRZ
PDQ\WLPHVHDFKHYHQWKDVEHHQSRVWHGSULRUWRHDFKZDLWIRUHYHQWVWRRFFXU
g 5HWXUQVWKHOHQJWKLQE\WHVRIWKHEXIIHUV
7KHEXIIHUVDQGWKHLUOHQJWKVDUHXVHGLQVXEVHTXHQWFDOOVWRWKHIXQFWLRQV
isc_wait_for_event()isc_que_events()DQGisc_event_counts()HYHQWBEXIIHULVXVHGWR
LQGLFDWHWKHHYHQWVRILQWHUHVWDQGWRKROGWKHFRXQWVLQHIIHFWEHIRUHDZDLWIRURQHRIWKH
HYHQWV$IWHUDQHYHQWLVSRVWHGUHVXOWBEXIIHULVILOOHGLQH[DFWO\DVHYHQWBEXIIHUH[FHSWWKDWWKH
HYHQWFRXQWVDUHXSGDWHGisc_event_counts()LVWKHQFDOOHGWRGHWHUPLQHZKLFKHYHQWVZHUH
SRVWHGEHWZHHQWKHWLPHWKHFRXQWVZHUHVHWLQHYHQWBEXIIHUDQGWKHWLPHWKHFRXQWVDUHVHWLQ
UHVXOWBEXIIHU

([DPSOH 7KHIROORZLQJSURJUDPIUDJPHQWLOOXVWUDWHVDFDOOWRisc_event_block()

API GUIDE 273

 CHAPTER 12 API FUNCTION REFERENCE

#define number_of_stocks 3;

char *event_buffer, *result_buffer;

long length;

length = isc_event_block(
&event_buffer,
&result_buffer,
number_of_stocks,
"DEC", "HP", "SUN");

5HWXUQ9DOXH isc_event_block()UHWXUQVDQXPEHUWKDWLVWKHVL]HLQE\WHVRIHDFKHYHQWSDUDPHWHU
EXIIHULWDOORFDWHV

6HH$OVR isc_event_counts()isc_que_events()isc_wait_for_event()

isc_event_counts()
&RPSDUHVHYHQWSDUDPHWHUEXIIHUV (3%V WRGHWHUPLQHZKLFKHYHQWVKDYHEHHQSRVWHGDQG
SUHSDUHVWKHHYHQWSDUDPHWHUEXIIHUVIRUWKHQH[WFDOOWRisc_que_events()RU
isc_wait_for_event()

6\QWD[ void isc_event_counts(

ISC_STATUS *status_vector,
short buffer_length,
char *event_buffer,
char *result_buffer);

Parameter Type Description

status_vector long * Pointer to the status vector, which is used to store the differences
in event counts for each corresponding event in event_buffer and
result_buffer
buffer_length short Length of the event parameter buffers, returned by the
isc_event_block() call that allocated them
event_buffer char * Pointer to the event parameter buffer that specifies the event
counts prior to the previous call to isc_wait_for_event() or
isc_que_events()
result_buffer char * Pointer to the event parameter buffer filled in as a result of
posting an event

274 INTERBASE 5
USING FUNCTION DEFINITIONS

'HVFULSWLRQ isc_event_counts()FRPSDUHVWKHHYHQWFRXQWVLQWKHHYHQWSDUDPHWHUEXIIHUVHYHQWBEXIIHU
DQGUHVXOWBEXIIHUDQGVHWVXSWRWKHILUVWHOHPHQWVRIVWDWXVBDUUD\WRFRQWDLQWKHGLIIHUHQFHV
,WWKHQPRGLILHVHYHQWBEXIIHUWRFRQWDLQWKHVDPHHYHQWFRXQWVDVUHVXOWBEXIIHULQSUHSDUDWLRQ
IRUWKHQH[WFDOOWRHLWKHUisc_wait_for_event() RU isc_que_events()
7KHFRXQWVLQHYHQWBEXIIHUVSHFLI\KRZPDQ\WLPHVHDFKHYHQWKDGEHHQSRVWHGVLQFHWKH
SUHYLRXVFDOOWRisc_event_wait() RU isc_que_events()7KHFRXQWVLQU HVXOWBEXIIHUHTXDOWKH
YDOXHVLQHYHQWBEXIIHUSOXVWKHQXPEHURIDGGLWLRQDOWLPHVDQHYHQWLVSRVWHGDIWHUWKHFXUUHQW
FDOOWRisc_event_wait()RUisc_que_events(),IDQHYHQWLVSRVWHGDIWHUDFDOOWRHLWKHURI
WKHVHIXQFWLRQVLWVFRXQWLVJUHDWHULQUHVXOWBEXIIHUWKDQLQHYHQWBEXIIHU2WKHUHYHQWFRXQWVPD\
DOVREHJUHDWHUEHFDXVHDQHYHQWPD\KDYHEHHQSRVWHGEHWZHHQFDOOVWRHLWKHURIWKHVH
IXQFWLRQV7KHYDOXHVLQVWDWXVBDUUD\DUHWKHGLIIHUHQFHVLQYDOXHVEHWZHHQHYHQWBEXIIHUDQG
UHVXOWBEXIIHU7KLVPHFKDQLVPRIFRPSDULQJDOOWKHFRXQWVHQVXUHVWKDWQRHYHQWSRVWLQJVDUH
PLVVHG

([DPSOH 7KHIROORZLQJSURJUDPIUDJPHQWLOOXVWUDWHVWKHVHWXSDQGZDLWLQJRQDQ\RIWKHHYHQWV
QDPHG´'(&µ´+3µRU´681µWKHQFDOOLQJisc_event_counts()WRGHWHUPLQHZKLFK
HYHQWVKDYHEHHQSRVWHG
#include <ibase.h>
#define number_of_stocks 3;

char *event_buffer, *result_buffer;

ISC_STATUS status_vector[20];
char *event_names[] = {"DEC", "HP", "SUN"};
long length;
int i;

length = isc_event_block(
&event_buffer,
&result_buffer,
number_of_stocks,
"DEC", "HP", "SUN");

isc_wait_for_event(
status_vector,
&database_handle, /* Set by previous isc_attach_database(). */
length, /* Returned from isc_event_block(). */
event_buffer,
result_buffer);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector); /* Display error message. */
return(1);

API GUIDE 275

 CHAPTER 12 API FUNCTION REFERENCE

isc_event_counts(
status_vector,
(short) length,
event_buffer,
result_buffer);

for (i=0; i<number_of_stocks; i++)

if (status_vector[i])
{
/* The event has been posted. Do whatever is appropriate, for
example,
initiating a buy or sell order. */
;
}

5HWXUQ9DOXH 1RQH

6HH$OVR isc_que_events()isc_wait_for_event()

isc_expand_dpb()
'\QDPLFDOO\EXLOGVRUH[SDQGVDGDWDEDVHSDUDPHWHUEXIIHU '3% WRLQFOXGHGDWDEDVH
SDUDPHWHUV

6\QWD[ void isc_expand_dpb(

char **dpb,
unsigned short *dpb_size,
. . .);

Parameter Type Description

dpb char ** Pointer to an existing DPB
dpb_size unsigned short * Pointer to the current size, in bytes, of the DPB
… char * Pointers to items to insert into the expanded DPB

276 INTERBASE 5
USING FUNCTION DEFINITIONS

'HVFULSWLRQ isc_expand_dpb()EXLOGVRUH[SDQGVD'3%G\QDPLFDOO\,WVPDLQXVHLVWRVLPSOLI\WKH
EXLOGLQJRIWKH'3%SULRUWRDFDOOWRisc_attach_database()RUWRDOORZDQHQGXVHUWR
VXSSO\DXVHUQDPHDQGSDVVZRUGFRPELQDWLRQDWUXQWLPH,QPDQ\FDVHVWKH'3%PXVWEH
FRQVWUXFWHGSURJUDPPDWLFDOO\EXWisc_expand_dpb()HQDEOHVDQDSSOLFDWLRQWRSDVVXVHU
QDPHVSDVVZRUGPHVVDJHILOHDQGFKDUDFWHUVHWSDUDPHWHUVWRWKHIXQFWLRQZKLFKWKHQ
DGGVWKHPWRDQH[LVWLQJ'3%
$SRLQWHUWRDSUHYLRXVO\DOORFDWHGDQGLQLWLDOL]HG'3%PXVWEHSDVVHGWR isc_expand_dpb()
DORQJZLWKDSRLQWHUWRDYDULDEOHFRQWDLQLQJWKHFXUUHQWVL]HRIWKH'3%ZKHQWKLVIXQFWLRQ
LVFDOOHG,IWKHVSDFHDOORFDWHGIRUWKH'3%LVQRWODUJHHQRXJKIRUWKHSDUDPHWHUVSDVVHGWR
isc_expand_dpb()WKHQWKHIXQFWLRQUHDOORFDWHVDODUJHU'3%SUHVHUYLQJLWVFXUUHQW
FRQWHQWVDQGDGGVWKHQHZSDUDPHWHUV
7RHQVXUHSURSHUPHPRU\PDQDJHPHQWDSSOLFDWLRQVWKDWFDOOisc_expand_dpb()VKRXOG
DOZD\VDOORFDWH'3%VODUJHHQRXJKWRKROGDOODQWLFLSDWHGSDUDPHWHUV

([DPSOH 7KHIROORZLQJFRGHFDOOVisc_expand_dpb()WRFUHDWHD'3%WKHQDWWDFKHVWRDGDWDEDVH
XVLQJWKHQHZO\FUHDWHG'3%XVHUBQDPHDQGXVHUBSDVVZRUGDUHDVVXPHGWREHYDULDEOHVZKRVH
YDOXHVKDYHEHHQILOOHGLQIRUH[DPSOHDIWHUDVNLQJWKHXVHUWRVSHFLI\WKHQDPHDQG
SDVVZRUGWREHXVHG
#include <ibase.h>
char *dpb;
ISC_STATUS status_vector[20];
isc_db_handle handle = NULL;
short dpb_length;

/* Build the database parameter buffer. */

dpb = (char *) malloc(50);

dpb_length = 0;

isc_expand_dpb(&dpb, &dpb_length, isc_dpb_user_name, user_name,

isc_dpb_password, user_password, NULL);

isc_attach_database(
status_vector,
0,
"employee.db",
&handle,
dpb_length,
dpb_buffer);
if (status_vector[0] == 1 && status_vector[1])
{
/* An error occurred. */

API GUIDE 277

 CHAPTER 12 API FUNCTION REFERENCE

isc_print_status(status_vector);
return(1);
}

5HWXUQ9DOXH 1RQH

6HH$OVR isc_attach_database()

isc_get_segment()
5HDGVDVHJPHQWIURPDQRSHQ%ORE

6\QWD[ ISC_STATUS isc_get_segment(

ISC_STATUS *status_vector,
isc_blob_handle *blob_handle,
unsigned short *actual_seg_length,
unsigned short seg_buffer_length,
char *seg_buffer);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
blob_handle isc_blob_handle * Pointer to the handle of the Blob you want to read.
actual_seg_length unsigned short * Pointer to the actual segment length that InterBase
reads into the buffer; useful if the segment length is
shorter than the buffer length
seg_buffer_length unsigned short Length of the segment buffer
seg_buffer char * Pointer to the segment buffer

'HVFULSWLRQ isc_get_segment() rHDGVD%OREVHJPHQWIURPDSUHYLRXVO\RSHQHG%ORE<RXFDQVHWWKH

VHJBEXIIHUBOHQJWK SDUDPHWHUWRDVL]HWKDWLVHIILFLHQWIRUDSDUWLFXODUW\SHRI%OREGDWD)RU
H[DPSOHLI\RXDUHUHDGLQJ%OREGDWDIURPDWH[WILOH\RXPLJKWVHWWKHVHJPHQWEXIIHU
OHQJWKWRWRWDNHDGYDQWDJHRIWKHWRFKDUDFWHUOLQHOHQJWKVWKDWDUHFRPPRQLQWH[W
ILOHV%\SHULRGLFDOO\FKHFNLQJWKHYDOXHRIWKHDFWXDOVHJPHQWOHQJWKLQ\RXUORRS\RXFDQ
GHWHUPLQHDQHQGRIOLQHRUHQGRIILOHFRQGLWLRQ
%HIRUHUHDGLQJDQ\SDUWRID%ORE\RXPXVWRSHQWKH%OREZLWKDFDOOWR isc_open_blob2()
isc_get_segment()EHKDYHVGLIIHUHQWO\GHSHQGLQJRQZKLFKFDOOSUHFHGHVLW,IWKHPRVW
UHFHQWFDOOLVWRisc_open_blob2()WKHQDFDOOWR isc_get_segment()UHDGVWKHILUVWVHJPHQW
LQWKH%ORE,IWKHPRVWUHFHQWFDOOLVWR isc_get_segment()WKHQLWUHDGVWKHQH[WVHJPHQW

278 INTERBASE 5
USING FUNCTION DEFINITIONS

,I%OREILOWHUVDUHVSHFLILHGZKHQD%ORELVRSHQHGWKHQHDFKVHJPHQWUHWULHYHGE\
isc_get_segment()LVILOWHUHGRQUHDG
Note %OREILOWHUVDUHQRWVXSSRUWHGRQ1HW:DUH
<RXFDQUHDGELWPDSVDQGRWKHUELQDU\ILOHVGLUHFWO\ZLWKRXWILOWHULQJXQOHVV\RXLQWHQGWR
FKDQJHIURPRQHIRUPDWWRDQRWKHUVD\IURP *(0WR%03<RXFDQDOVRVWRUHFRPSUHVVHG
ELWPDSVGLUHFWO\LQDGDWDEDVHLQIRUPDWVVXFKDV-3* -3(* %03 :LQGRZVQDWLYH
ELWPDSV RU*,) &RPSX6HUYH*UDSKLF,QWHUFKDQJH)RUPDW 1RILOWHULQJLVUHTXLUHG
<RXFDQVWRUHELWPDSVLQDGDWDEDVHLQURZPDMRURUFROXPQPDMRURUGHU
,IWKHEXIIHULVQRWODUJHHQRXJKWRKROGWKHHQWLUHFXUUHQWVHJPHQWWKHIXQFWLRQUHWXUQV
LVFBVHJPHQWDQGWKHQH[WFDOOWRisc_get_segment()JHWVWKHQH[WFKXQNRIWKHRYHUVL]HG
VHJPHQWUDWKHUWKDQJHWWLQJWKHQH[WVHJPHQW
:KHQisc_get_segment()UHDGVWKHODVWVHJPHQWRIWKH%OREWKHIXQFWLRQUHWXUQVWKHFRGH
LVFBVHJVWUBHRI
)RUPRUHLQIRUPDWLRQDERXWUHDGLQJGDWDIURPD%OREVHH&KDSWHU´:RUNLQJZLWK%ORE
'DWDµ

([DPSOH 7KHIROORZLQJFDOOJHWVDVHJPHQWIURPRQH%OREDQGZULWHVLWWRDQRWKHU
get_status = isc_get_segment(status, &from_blob, &seg_len, 80, buffer);
if (status[0] == 1 && status[1])
{
isc_print_status(status);
return(1);
}
if (get_status != isc_segstr_eof)
write_status = isc_put_segment(status, &to_blob, seg_len, buffer);
if (status[0] == 1 && status[1])
{
isc_print_status(status);
return(1);
}

5HWXUQ9DOXH isc_get_segment()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHVVXFFHVV
LVFBVHJPHQWLQGLFDWHVWKHEXIIHULVQRWODUJHHQRXJKWRKROGWKHHQWLUHFXUUHQWVHJPHQWWKH
QH[WFDOOWRisc_get_segment()JHWVWKHQH[WFKXQNRIWKHRYHUVL]HGVHJPHQWUDWKHUWKDQ
JHWWLQJWKHQH[WVHJPHQWLVFBVHJVWUBHRILQGLFDWHVWKDWWKHODVWVHJPHQWRIWKH%OREKDVEHHQ
UHDG$Q\RWKHUQRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRI
WKHVWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH

API GUIDE 279

 CHAPTER 12 API FUNCTION REFERENCE

7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_create_blob2()isc_open_blob2()isc_put_segment()

isc_interprete()
([WUDFWVWKHWH[WIRUDQ,QWHU%DVHHUURUPHVVDJHIURPWKHHUURUVWDWXVYHFWRUWRDXVHUGHILQHG
EXIIHU

6\QWD[ ISC_STATUS isc_interprete(

char *buffer,
ISC_STATUS **status_vector);

Parameter Type Description

buffer char * Application buffer for storing an InterBase error message
status_vector ISC_STATUS ** Pointer to a pointer to the error status vector

'HVFULSWLRQ *LYHQERWKWKHORFDWLRQRIDVWRUDJHEXIIHUDOORFDWHGLQDSURJUDPDQGWKHDGGUHVVRIWKH
VWDWXVYHFWRUisc_interprete()EXLOGVDQHUURUPHVVDJHVWULQJIURPWKHLQIRUPDWLRQLQWKH
VWDWXVYHFWRUSXWVWKHIRUPDWWHGVWULQJLQWKHEXIIHUZKHUHWKHSURJUDPFDQPDQLSXODWHLW
DQGDGYDQFHVWKHVWDWXVYHFWRUSRLQWHUWRWKHVWDUWRIWKHQH[WFOXVWHURIHUURUPHVVDJH
LQIRUPDWLRQ)RUH[DPSOH\RXPLJKWGHFODUHDQHUURUVWULQJEXIIHUFDOOisc_interprete()WR
UHWULHYHWKHILUVWHUURUPHVVDJHDQGLQVHUWWKHPHVVDJHLQWRWKHEXIIHUZULWHWKHEXIIHUWRD
ORJILOHWKHQSHHNDWWKHQH[WFOXVWHUWRVHHLILWFRQWDLQVPRUHHUURULQIRUPDWLRQ
isc_interprete()UHWULHYHVDQGIRUPDWVDVLQJOHPHVVDJHHDFKWLPHLWLVFDOOHG:KHQDQHUURU
RFFXUVKRZHYHUWKHVWDWXVYHFWRUXVXDOO\FRQWDLQVPRUHWKDQRQHHUURUPHVVDJH7RUHWULHYH
DOOUHOHYDQWHUURUPHVVDJHV\RXPXVWPDNHUHSHDWHGFDOOVWRisc_interprete()XQWLOQRPRUH
PHVVDJHVDUHUHWXUQHG
Note 'RQRWSDVVWKHDGGUHVVRIWKHVWDWXVYHFWRUGLUHFWO\EHFDXVHHDFKWLPH
isc_interprete()LVFDOOHGLWPRGLILHVWKHSRLQWHUWRWKHVWDWXVYHFWRUWRSRLQWWRWKHVWDUWRI
WKHQH[WDYDLODEOHPHVVDJH
7RGLVSOD\DOOHUURUPHVVDJHVRQWKHVFUHHQLQVWHDGRIWRDEXIIHUXVHisc_print_status()

([DPSOH 7KHIROORZLQJFRGHGHFODUHVDPHVVDJHEXIIHUDVWDWXVYHFWRUDQGDSRLQWHUWRWKHYHFWRU
WKHQLOOXVWUDWHVKRZUHSHDWHGFDOOVDUHPDGHWRisc_interprete()WRVWRUHDOOPHVVDJHVLQWKH
EXIIHU

280 INTERBASE 5
USING FUNCTION DEFINITIONS

#include <ibase.h>
char msg[512];
ISC_STATUS status_vector[20];
long *pvector; /* Pointer to pointer to status vector. */
FILE *efile; /* Code fragment assumes this points to an open file. */
. . .
pvector = status_vector; /* (Re)set to start of status vector. */
isc_interprete(msg, &pvector); /* Retrieve first message. */
fprintf(efile, "%s\n", msg); /* Write buffer to log file. */
msg[0] = ’-’; /* Append leading hyphen to secondary messages. */
while(isc_interprete(msg + 1,&pvector)) /* More messages? */
{
fprintf(efile, "%s\n", msg); /* If so, write them, too. */
}
fclose(efile);
. . .

5HWXUQ9DOXH ,IVXFFHVVIXOisc_interprete()UHWXUQVWKHOHQJWKRIWKHHUURUPHVVDJHVWULQJLWVWRUHVLQ
EXIIHU,WDOVRDGYDQFHVWKHVWDWXVYHFWRUSRLQWHUWRWKHVWDUWRIWKHQH[WFOXVWHURIHUURU
PHVVDJHLQIRUPDWLRQ
,IWKHUHDUHQRPRUHPHVVDJHVLQWKHVWDWXVYHFWRURULI isc_interprete()FDQQRWLQWHUSUHWWKH
QH[WPHVVDJHLWUHWXUQV

6HH$OVR isc_print_sqlerror()isc_print_status()isc_sqlcode()isc_sql_interprete()

API GUIDE 281

 CHAPTER 12 API FUNCTION REFERENCE

isc_modify_user( )
0RGLILHVDXVHUUHFRUGIURPWKHSDVVZRUGGDWDEDVHLVFJGE

6\QWD[ ISC_STATUS isc_modify_user(

ISC_STATUS *status
USER_SEC_DATA *user_sec_data);

Parameter Type Description

status vector ISC_STATUS * Pointer to the error status vector
user_sec_data USER_SEC_DATA * Pointer to a struct that is defined in ibase.h

'HVFULSWLRQ 7KHWKUHHVHFXULW\IXQFWLRQVisc_add_user()isc_delete_user()DQGisc_modify_user()
PLUURUIXQFWLRQDOLW\WKDWLVDYDLODEOHLQWKHgsecFRPPDQGOLQHXWLOLW\isc_modify_user()
PRGLILHVDUHFRUGIURPLVFJGE,QWHU%DVH·VSDVVZRUGGDWDEDVH
$WDPLQLPXP\RXPXVWSURYLGHWKHXVHUQDPH$Q\DGGLWLRQDOXVHULQIRUPDWLRQWKDW\RX
VXSSO\VXFKDVILUVWQDPHODVWQDPHRUSDVVZRUGRYHUZULWHVWKHLQIRUPDWLRQWKDWLVDOUHDG\
LQLVFJGE
,IWKHVHUYHULVQRWORFDO\RXPXVWSURYLGHERWKDVHUYHUQDPHDQGDSURWRFRO9DOLGFKRLFHV
IRUWKHSURWRFROILHOGDUHVHFBSURWRFROBWFSLSVHFBSURWRFROBQHWEHXLVHFBSURWRFROBVS[DQG
VHFBSURWRFROBORFDO
,QWHU%DVHUHDGVWKHVHWWLQJVIRUWKH,6&B86(5DQG,6&B3$66:25'HQYLURQPHQWYDULDEOHVLI
\RXGRQRWSURYLGHD'%$XVHUQDPHDQGSDVVZRUG
7KHGHILQLWLRQIRUWKH86(5B6(&B'$7$VWUXFWLQLEDVHKLVDVIROORZV
typedef struct {
short sec_flags; /* which fields are specified */
int uid; /* the user’s id */
int gid; /* the user’s group id */
int protocol; /* protocol to use for connection */
char *server; /* server to administer */
char *user_name; /* the user’s name */
char *password; /* the user’s password */
char *group_name; /* the group name */
char *first_name; /* the user’s first name */
char *middle_name; /* the user’s middle name */
char *last_name; /* the user’s last name */
char *dba_user_name; /* the dba user name */

282 INTERBASE 5
USING FUNCTION DEFINITIONS

char *dba_password; /* the dba password */

} USER_SEC_DATA;

:KHQ\RXSDVVWKLVVWUXFWWRRQHRIWKHWKUHHVHFXULW\IXQFWLRQV\RXFDQWHOOLWZKLFKILHOGV
\RXKDYHVSHFLILHGE\GRLQJDELWZLVH25RIWKHIROORZLQJYDOXHVZKLFKDUHGHILQHGLQLEDVHK
sec_uid_spec 0x01
sec_gid_spec 0x02
sec_server_spec 0x04
sec_password_spec 0x08
sec_group_name_spec 0x10
sec_first_name_spec 0x20
sec_middle_name_spec 0x40
sec_last_name_spec 0x80
sec_dba_user_name_spec 0x100
sec_dba_password_spec 0x200

1RELWYDOXHVDUHDYDLODEOHIRUXVHUQDPHDQGSDVVZRUGVLQFHWKH\DUHUHTXLUHG
7KHIROORZLQJHUURUPHVVDJHVH[LVWIRUWKLVIXQFWLRQ

Code Value Description

isc_usrname_too_long 335544747 The user name passed in is greater than 31 bytes
isc_password_too_long 335544748 The password passed in is longer than 8 bytes
isc_usrname_required 335544749 The operation requires a user name
isc_password_required 335544750 The operation requires a password
isc_bad_protocol 335544751 The protocol specified is invalid
isc_dup_usrname_found 335544752 The user name being added already exists in the security
database.
isc_usrname_not_found 335544753 The user name was not found in the security database
isc_error_adding_sec_record 335544754 An unknown error occurred while adding a user
isc_error_deleting_sec_record 335544755 An unknown error occurred while deleting a user
isc_error_modifying_sec_record 335544756 An unknown error occurred while modifying a user
isc_error_updating_sec_db 335544757 An unknown error occurred while updating the security
database
TABLE 12.19 Error messages for user security functions

API GUIDE 283

 CHAPTER 12 API FUNCTION REFERENCE

([DPSOH 7KHIROORZLQJH[DPSOHPRGLILHVLVFJGEWRFKDQJHWKHSDVVZRUGIRUWKHXVHU6RFNVXVLQJ
WKHELWZLVH25WHFKQLTXHIRUSDVVLQJYDOXHVIURPWKH86(5B6(&B'$7$VWUXFW
{
ISC_STATUS status[20];
USER_SEC_DATA sec;

sec.server = "kennel";
sec.dba_user_name = "sysdba";
sec.dba_password = "masterkey";
sec.protocol = sec_protocol_tcpip;
sec.user_name = "socks";
sec.password = "feed_me!"; /* Note: do not hardcode passwords */
sec.sec_flags = sec_server_spec
| sec_password_spec
| sec_dba_user_name_spec
| sec_dba_password_spec;

isc_add_user(status, &sec);
/* check status for errors */
if (status[0] == 1 && status[1])
{
switch (status[1]) {
case isc_usrname_too_long:
printf("Security database cannot accept long user names\n");
break;
...
}
}
}

5HWXUQ9DOXH isc_modify_user()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHVVXFFHVV
$QRQ]HURYDOXHLQGLFDWHVDQHUURU6HHWKH´'HVFULSWLRQµVHFWLRQIRUWKLVIXQFWLRQIRUDOLVW
RIHUURUFRGHV)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU
´+DQGOLQJ(UURU&RQGLWLRQVµ

6HH$OVR isc_add_user()isc_delete_user()

284 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_open_blob2()
2SHQVDQH[LVWLQJ%OREIRUUHWULHYDODQGRSWLRQDOILOWHULQJ

6\QWD[ ISC_STATUS isc_open_blob2(

ISC_STATUS *status_vector,
isc_db_handle *db_handle,
isc_tr_handle *trans_handle,
isc_blob_handle *blob_handle,
ISC_QUAD *blob_id,
short bpb_length,
char *bpb_address);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
db_handle isc_db_handle * Pointer to a database handle set by a previous call to
isc_attach_database()
db_handle returns an error in status_vector if it is NULL
trans_handle isc_tr_handle * Pointer to a transaction handle whose value has been set by a
previous isc_start_transaction() call; trans_handle returns
an error if NULL
blob_handle isc_blob_handle * Pointer to the Blob handle, which must be NULL when you
make this call
blob_id ISC_QUAD * Pointer to the 64-bit system-defined Blob ID, which is stored
in a field in the table and points to the first segment of the
Blob or to a page of pointers to Blob fragments
bpb_length short Length of the Blob parameter buffer (BPB)
bpb_address char * Pointer to the BPB

'HVFULSWLRQ isc_open_blob2() RSHQVDQH[LVWLQJ%OREIRUUHWULHYDODQGRSWLRQDOILOWHULQJIURPRQH%ORE

VXEW\SHWRDQRWKHU
Note 8VLQJ%OREILOWHUVLVQRWVXSSRUWHGRQ1HW:DUH
,QSXWDQGRXWSXW%OREILOWHUW\SHVDUHSDVVHGWRisc_open_blob2()DVVXEW\SHLQIRUPDWLRQ
LQDSUHYLRXVO\SRSXODWHG%3%SRLQWHGWRE\ESEBDGGUHVV,I%OREILOWHUVDUHQRWQHHGHGRU
FDQQRWEHXVHGD%3%LVQRWQHHGHGSDVVIRUESEBOHQJWKDQG18//IRUESEBDGGUHVV

API GUIDE 285

 CHAPTER 12 API FUNCTION REFERENCE

7KHEOREBLGLGHQWLILHVZKLFKSDUWLFXODU%ORELVWREHRSHQHG7KLVEOREBLGLVVHWE\DVHTXHQFH
RI'64/IXQFWLRQFDOOV
2QVXFFHVVisc_open_blob2()DVVLJQVDXQLTXH,'WREOREBKDQGOH6XEVHTXHQW$3,FDOOVXVH
WKLVKDQGOHWRLGHQWLI\WKH%OREDJDLQVWZKLFKWKH\RSHUDWH
$IWHUDEORELVRSHQHGLWVGDWDFDQEHUHDGE\DVHTXHQFHRIFDOOVWRisc_get_segment()
:KHQILQLVKHGDFFHVVLQJWKH%OREFORVHLWZLWKisc_close_blob()
)RUPRUHLQIRUPDWLRQDERXWRSHQLQJD%OREIRUUHWULHYDODQGRSWLRQDOILOWHULQJVHH&KDSWHU
´:RUNLQJZLWK%ORE'DWDµ

([DPSOH 7KHIROORZLQJIUDJPHQWLVH[FHUSWHGIURPWKHH[DPSOHILOHDSLF7KHH[DPSOHSURJUDP
GLVSOD\VMREGHVFULSWLRQVWKDWDUHSDVVHGWKURXJKDILOWHU
while ((fetch_stat = isc_dsql_fetch(status, &stmt, 1, sqlda)) == 0)
{
printf("\nJOB CODE: %5s GRADE: %d", job_code, job_grade);
printf(" COUNTRY: %-20s\n\n", job_country);
/* Open the blob with the fetched blob_id. */
isc_open_blob2(status, &DB, &trans, &blob_handle, &blob_id, 9, bpb);
if (status[0] == 1 && status[1])
{
isc_print_status(status);
return(1);
}
}

5HWXUQ9DOXH isc_open_blob2()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHVVXFFHVV
$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKHVWDWXV
YHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_close_blob()

286 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_prepare_transaction()
([HFXWHVWKHILUVWSKDVHRIDWZRSKDVHFRPPLWDJDLQVWPXOWLSOHGDWDEDVHV

6\QWD[ ISC_STATUS isc_prepare_transaction(

ISC_STATUS *status_vector,
isc_tr_handle *trans_handle);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
trans_handle isc_tr_handle * Pointer to a transaction handle whose value has been set by a
previous isc_start_transaction() call; trans_handle returns an
error if NULL

'HVFULSWLRQ isc_prepare_transaction()LQLWLDWHVWKHILUVWSKDVHRIDWZRSKDVHFRPPLWXQGHUSURJUDP
GLUHFWLRQ,WDOHUWV,QWHU%DVHZKLFKSROOVDOOGDWDEDVHSDUWLFLSDQWVDQGZDLWVIRUUHSOLHV7KH
isc_prepare_transaction()IXQFWLRQSXWVWKHWUDQVDFWLRQLQOLPER
%HFDXVHDFDOOWRWKLVIXQFWLRQLQGLFDWHVWKDW\RXLQWHQGWRFRQWURODOOSKDVHVRIWKHFRPPLW
\RXPXVWFRPSOHWHWKHVHFRQGSKDVHRIWKHFRPPLWE\H[SOLFLWO\FDOOLQJWKH
isc_commit_transaction()IXQFWLRQ
,IDFDOOWRisc_prepare_transaction()IDLOVWKHDSSOLFDWLRQVKRXOGUROOEDFNWKHWUDQVDFWLRQ
ZLWKDFDOOWR WKH isc_rollback_transaction()IXQFWLRQ
Note ,I\RXZDQW,QWHU%DVHWRDXWRPDWLFDOO\SHUIRUPWKHWZRSKDVHFRPPLWFDOO
isc_commit_transaction()ZLWKRXWFDOOLQJisc_prepare_transaction()

([DPSOH 7KHIROORZLQJH[DPSOHH[HFXWHVWKHILUVWSKDVHRIDWZRSKDVHFRPPLWDQGLQFOXGHVD
UROOEDFNLQFDVHRIIDLOXUH
isc_prepare_transaction(status_vector, &trans);
if (status_vector[0] == 1 && status_vector[1])
rb_status = isc_rollback_transaction(status_vector, &trans)
else
{
isc_commit_transaction(status_vector, &trans);
if (!(status_vector[0] == 1 && status_vector[1]))
fprintf("Commit successful.");
}

API GUIDE 287

 CHAPTER 12 API FUNCTION REFERENCE

5HWXUQ9DOXH isc_prepare_transaction()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_commit_transaction()
isc_prepare_transaction2()
isc_rollback_transaction()

isc_prepare_transaction2()
3HUIRUPVWKHILUVWSKDVHRIDWZRSKDVHFRPPLWIRUPXOWLGDWDEDVHWUDQVDFWLRQV

6\QWD[ ISC_STATUS isc_prepare_transaction2(

ISC_STATUS *status_vector,
isc_tr_handle *trans_handle,
unsigned short msg_length,
char *message);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
trans_handle isc_tr_handle * Pointer to a transaction handle whose value has been set by
a previous isc_start_transaction() call; trans_handle
returns an error if NULL
msg_length unsigned short Length of message in bytes
message char * Transaction description buffer

'HVFULSWLRQ isc_prepare_transaction2()SHUIRUPVWKHILUVWSKDVHRIDWZRSKDVHFRPPLWMXVWDV
isc_prepare_transaction()GRHVEXWisc_prepare_transaction2()H[SHFWV\RXWRSURYLGH
WZRDGGLWLRQDODUJXPHQWV
g $QLQIRUPDWLRQPHVVDJHWRZULWHWRWKH5'%75$16$&7,21B'(6&5,37,21FROXPQLQWKH
5'%75$16$&7,216V\VWHPWDEOHWKDWGHVFULEHVWKHWUDQVDFWLRQWRFRPPLWVRWKDWUHFRYHU\
LVSRVVLEOHLQWKHHYHQWDV\VWHPFUDVKRFFXUVGXULQJWKHFRPSOHWLRQRIWKHFRPPLW
g 7KHOHQJWKLQE\WHVRIWKHLQIRUPDWLRQPHVVDJH

288 INTERBASE 5
USING FUNCTION DEFINITIONS

%\HOHFWLQJWRXVH isc_prepare_transaction2()\RXDUHLQHIIHFWGLVDEOLQJWKHDXWRPDWLF
UHFRYHU\IXQFWLRQVLQKHUHQWLQWKHWZRSKDVHFRPPLW,WLV\RXUUHVSRQVLELOLW\WRGHDOZLWK
UHFRYHU\LVVXHVWKDWPLJKWRFFXUGXULQJIDLOXUHRIWKHWZRSKDVHFRPPLW1RUPDOO\,QWHU%DVH
DXWRPDWLFDOO\ZULWHVWRWKH5'%75$16$&7,21B'(6&5,37,21FROXPQLQWKH
5'%75$16$&7,216V\VWHPWDEOHLQIRUPDWLRQWKDWPDNHVLWSRVVLEOHWRUHFRQQHFWIROORZLQJ
DV\VWHPFUDVKGXULQJWKHFRPPLW<RXFDQPDQXDOO\ZULWHDPHVVDJHVWULQJLQWR
5'%75$16$&7,216E\XVLQJWKHPHVVDJHSDUDPHWHULQWKLVIXQFWLRQ
$WWKHULVNRISUHYHQWLQJUHFRYHU\LQWKHHYHQWRIDV\VWHPFUDVK\RXPLJKWFKRRVHWRDYRLG
ZULWLQJDPHVVDJHWR5'%75$16$&7,21DOWRJHWKHULI\RXGHWHUPLQHWKDWWKHUHLVWRRPXFK
RYHUKHDGDVVRFLDWHGZLWKWKLVH[WUDDFWLRQHYHU\WLPH\RXUDSSOLFDWLRQFRPPLWV

([DPSOH 7KHIROORZLQJH[DPSOHH[HFXWHVWKHILUVWSKDVHRIDWZRSKDVHFRPPLWDQGLQFOXGHVD
UROOEDFNLQFDVHRIIDLOXUH
isc_prepare_transaction2(status_vector, &trans, msg_len, msg);
if (status_vector[0] == 1 && status_vector[1])
rb_status = isc_rollback_transaction(status_vector, &trans);

5HWXUQ9DOXH isc_prepare_transaction2()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HUR
LQGLFDWHVVXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQW
RIWKHVWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_commit_transaction()
isc_prepare_transaction()
isc_rollback_transaction()

isc_print_sqlerror()
'LVSOD\VDQ64/&2'(YDOXHDFRUUHVSRQGLQJ64/HUURUPHVVDJHDQGDQ\DGGLWLRQDO
,QWHU%DVHHUURUPHVVDJHVLQWKHHUURUVWDWXVYHFWRU

6\QWD[ void isc_print_sqlerror(

short SQLCODE,
ISC_STATUS *status_vector);

Parameter Type Description

SQLCODE short Variable containing an SQLCODE value
status_vector ISC_STATUS * Pointer to the error status vector

API GUIDE 289

 CHAPTER 12 API FUNCTION REFERENCE

'HVFULSWLRQ 'XULQJWKHSURFHVVLQJRI'64/$3,FDOOV64/HUURUVFDQRFFXU64/HUURUVDUHJHQHUDOO\
UHSRUWHGLQDYDULDEOHFDOOHG64/&2'('64/FDOOVUHWXUQHUURULQIRUPDWLRQWRD
XVHUGHILQHGHUURUVWDWXVYHFWRUOLNHDQ\RWKHU$3,FDOOEXWisc_print_sqlerror()FDQEH
XVHGWRLQWHUSUHWWKHSULPDU\HUURUFRQGLWLRQDVDQ64/HUURUPHVVDJHIRUGLUHFWGLVSOD\RQ
WKHVFUHHQ7RXVHisc_print_sqlerror()DQDSSOLFDWLRQPXVWGHFODUHERWKDQ64/&2'(
YDULDEOHIRUKROGLQJWKH64/HUURUQXPEHUDQGDQHUURUVWDWXVYHFWRUIRUKROGLQJ,QWHU%DVH
HUURULQIRUPDWLRQisc_print_sqlerror()GLVSOD\VWKH64/&2'(YDOXHDUHODWHG64/HUURU
PHVVDJHDQGDQ\DGGLWLRQDO,QWHU%DVHHUURUPHVVDJHVLQWKHVWDWXVDUUD\
Note 6RPHZLQGRZLQJV\VWHPVGRQRWSHUPLWGLUHFWVFUHHQZULWHV'RQRWXVH
isc_print_sqlerror()ZKHQGHYHORSLQJDSSOLFDWLRQVIRUWKHVHHQYLURQPHQWV,QVWHDGXVH
isc_sql_interprete()DQGisc_interprete()WRFDSWXUHPHVVDJHVWRDEXIIHUIRUGLVSOD\

([DPSOH 7KHIROORZLQJFRGHFDOOVisc_print_sqlerror()ZKHQDQHUURURFFXUV
#include <ibase.h>
long SQLCODE;
ISC_STATUS status_vector[20];
. . .
if (status_vector[0] == 1 && status_vector[1])
{
SQLCODE = isc_sqlcode(status_vector);
isc_print_sqlerror(SQLCODE, status_vector);
}

5HWXUQ9DOXH 1RQH

6HH$OVR isc_interprete()isc_print_status()isc_sql_interprete()isc_sqlcode()

isc_print_status()
%XLOGVDQGGLVSOD\VHUURUPHVVDJHVEDVHGRQWKHFRQWHQWVRIWKH,QWHU%DVHHUURUVWDWXVYHFWRU

6\QWD[ ISC_STATUS isc_print_status(ISC_STATUS *status_vector);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector

'HVFULSWLRQ isc_print_status()EXLOGVDOOHUURUPHVVDJHVEDVHGRQWKHFRQWHQWVRIWKHHUURUVWDWXV
YHFWRUDQGGLVSOD\VWKHPRQWKHVFUHHQVWDWXVBYHFWRUPXVWEHGHFODUHGLQWKHSURJUDPDVDQ
DUUD\RIWZHQW\HOHPHQWV

290 INTERBASE 5
USING FUNCTION DEFINITIONS

([DPSOH 7KHIROORZLQJFRGHGLVSOD\VHUURUPHVVDJHVZKHQDQHUURURFFXUVGXULQJSURFHVVLQJ
#include <ibase.h>
ISC_STATUS status_vector[20];
. . .
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector);
return(1);
}

5HWXUQ9DOXH isc_print_status()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHVVXFFHVV
$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKHVWDWXV
YHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_interprete()isc_print_sqlerror()isc_sqlcode()isc_sql_interprete()

isc_put_segment()
:ULWHVD%OREVHJPHQW

6\QWD[ ISC_STATUS isc_put_segment(

ISC_STATUS *status_vector,
isc_blob_handle *blob_handle,
unsigned short seg_buffer_length,
char *seg_buffer);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
blob_handle isc_blob_handle * Pointer to the handle of the Blob to which you want to
write; use isc_create_blob2() to set a value for this
handle
seg_buffer_length unsigned short Length of the Blob segment buffer
seg_buffer_address char * Pointer to the Blob segment buffer that contains data
for writing

API GUIDE 291

 CHAPTER 12 API FUNCTION REFERENCE

'HVFULSWLRQ isc_put_segment() ZULWHVD%OREVHJPHQWLQVHJBEXIIHUBDGGUHVVWRD%ORESUHYLRXVO\FUHDWHG

DQGRSHQHGZLWKisc_create_blob2()
,ID%OREILOWHUZDVVSHFLILHGZKHQWKH%OREZDVFUHDWHGWKHQHDFKVHJPHQWLVILOWHUHGEHIRUH
VWRULQJWKHUHVXOWLQWRWKH%ORE
7KHEHKDYLRURIisc_put_segment()GHSHQGVRQZKDWFDOOSUHFHGHGLW,IWKHPRVWUHFHQW
FDOOZDVWRisc_create_blob()RU isc_create_blob2()WKHQDFDOOWR isc_put_segment()
ZULWHVWKHILUVWVHJPHQWRIWKH%ORE,IWKHPRVWUHFHQWFDOOZDVWR isc_put_segment()WKHQ
LWZULWHVWKHQH[WVHJPHQW
<RXFDQZULWHELWPDSVDQGRWKHUELQDU\ILOHVGLUHFWO\ZLWKRXWILOWHULQJXQOHVV\RXLQWHQGWR
FKDQJHIURPRQHIRUPDWWRDQRWKHUVD\IURP*(0WR%03<RXFDQDOVRVWRUHFRPSUHVVHG
ELWPDSVGLUHFWO\LQDGDWDEDVHLQIRUPDWVVXFKDV-3* -3(* %03 :LQGRZVQDWLYH
ELWPDSV RU*,) &RPSX6HUYH*UDSKLF,QWHUFKDQJH)RUPDW 
<RXFDQVWRUHELWPDSVLQ\RXUGDWDEDVHLQURZPDMRURUFROXPQPDMRURUGHU
<RXFDQQRWXSGDWHD%OREGLUHFWO\,I\RXZDQWWRPRGLI\%OREGDWD\RXPXVWGRRQHRIWKH
IROORZLQJ
g &UHDWHDQHZ%ORE
g 5HDGWKHROG%OREGDWDLQWRDEXIIHUZKHUH\RXFDQHGLWRUPRGLI\LW
g :ULWHWKHPRGLILHGGDWDWRWKHQHZ%ORE
g 3UHSDUHDQGH[HFXWHDQ83'$7(VWDWHPHQWWKDWZLOOPRGLI\WKH%OREFROXPQWRFRQWDLQWKH
%ORE,'RIWKHQHZ%OREUHSODFLQJWKHROG%ORE·V%ORE,'
)RUPRUHLQIRUPDWLRQDERXWFUHDWLQJDQGZULWLQJ%OREGDWDVHH&KDSWHU´:RUNLQJZLWK
%ORE'DWDµ
Note 7RUHDGDVHJPHQWWKDW\RXZURWHZLWKDFDOOWRisc_put_segment()\RXPXVWFORVH
WKH%OREZLWKisc_close_blob()DQGWKHQRSHQLWZLWK isc_open_blob2()

([DPSOH 7KHIROORZLQJH[DPSOHUHDGVDVHJPHQWRIRQH%OREDQGZULWHVLWWRDQRWKHU%ORE
get_status = isc_get_segment(status, &from_blob, &seg_len, 80, buffer);
if (status[0] == 1 && status[1])
{
isc_print_status(status);
return(1);
}
if (get_status != isc_segstr_eof)
write_status = isc_put_segment(status, &to_blob, seg_len, buffer);
if (status[0] == 1 && status[1])
{
isc_print_status(status);
return(1);

292 INTERBASE 5
USING FUNCTION DEFINITIONS

5HWXUQ9DOXH isc_put_segment()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHVVXFFHVV
$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKHVWDWXV
YHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_close_blob()isc_get_segment()isc_open_blob2()

isc_que_events()
5HTXHVWVDV\QFKURQRXVQRWLILFDWLRQRIRQHRIDVSHFLILHGJURXSRIHYHQWV

6\QWD[ ISC_STATUS isc_que_events(

ISC_STATUS *status_vector,
isc_db_handle *db_handle,
ISC_LONG *event_id,
short length,
char *event_buffer,
isc_callback event_function,
void *event_function_arg);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
db_handle isc_db_handle * Pointer to a database handle set by a previous call to
isc_attach_database(); the handle identifies the
database against which the events are expected to be
posted
db_handle returns an error in status_vector if it is NULL
event_id ISC_LONG * Pointer to an event identifier to set
length short Length of the event parameter buffers, returned by the
isc_event_block() call which allocated them

API GUIDE 293

 CHAPTER 12 API FUNCTION REFERENCE

Parameter Type Description

event_buffer char * Pointer to the event parameter buffer that specifies the
current counts of the events to be waited on; this buffer
should have been initially allocated and filled in by a call
to isc_event_block()
event_function isc_callback Pointer to the address of the function to receive event
notification
event_function_arg void * First argument to be passed to event_function, usually a
pointer to the event parameter buffer you want filled in
with updated event counts

'HVFULSWLRQ isc_que_events()LVFDOOHGWRUHTXHVWDV\QFKURQRXVQRWLILFDWLRQRIDQ\RIWKHHYHQWVOLVWHG
LQHYHQWBEXIIHU8SRQFRPSOHWLRQRIWKHFDOOEXWEHIRUHHYHQWVDUHSRVWHGFRQWUROLVUHWXUQHG
WRWKHFDOOLQJDSSOLFDWLRQZKLFKFDQFRQWLQXHRWKHUSURFHVVLQJ:KHQDUHTXHVWHGHYHQWLV
SRVWHG,QWHU%DVHFDOOVWKHIXQFWLRQVSHFLILHGLQHYHQWBIXQFWLRQWRSURFHVVHYHQWRFFXUUHQFH
$IWHUHYHQWBIXQFWLRQLVFDOOHG\RXPXVWFDOOisc_que_events()DJDLQLI\RXZDQWWRVWDUWDQRWKHU
DV\QFKURQRXVZDLWRQWKHVSHFLILHGHYHQWV
Note isc_que_events()FDQQRWEHFDOOHGIURPZLWKLQHYHQWBIXQFWLRQ
,I\RXZDQWWRFDQFHO\RXUisc_que_events()UHTXHVWIRUDV\QFKURQRXVHYHQWQRWLILFDWLRQ
FDOOisc_cancel_events()
Note 7RUHTXHVWV\QFKURQRXVQRWLILFDWLRQFDOOisc_wait_for_event()

([DPSOH 7KHIROORZLQJSURJUDPIUDJPHQWLOOXVWUDWHVFDOOLQJisc_que_events()WRZDLW
DV\QFKURQRXVO\IRUHYHQWRFFXUUHQFHV:LWKLQDORRSLWSHUIRUPVRWKHUSURFHVVLQJDQG
FKHFNVWKHHYHQWIODJ SUHVXPDEO\VHWE\WKHVSHFLILHGHYHQWIXQFWLRQ WRGHWHUPLQHZKHQDQ
HYHQWKDVEHHQSRVWHG,IRQHKDVWKHSURJUDPUHVHWVWKHHYHQWIODJFDOOV
isc_event_counts()WRGHWHUPLQHZKLFKHYHQWVKDYHEHHQSRVWHGVLQFHWKHODVWFDOOWR
isc_que_events()DQGFDOOVisc_que_events()WRLQLWLDWHDQRWKHUDV\QFKURQRXVZDLW
#include <ibase.h>
#define number_of_stocks 3;
#define MAX_LOOP 10

char *event_names[] = {"DEC", "HP", "SUN"};

char *event_buffer, *result_buffer;
ISC_STATUS count_array[number_of_stocks];
short length;
ISC_LONG event_id;
int i, counter;
int event_flag = 0;

294 INTERBASE 5
USING FUNCTION DEFINITIONS

length = (short)isc_event_block(
&event_buffer,
&result_buffer,
number_of_stocks,
"DEC", "HP", "SUN");

isc_que_events(
status_vector,
&database_handle, /* Set in previous isc_attach_database(). */
&event_id,
length, /* Returned from isc_event_block(). */
event_buffer,
(isc_callback)event_function,
result_buffer);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector); /* Display error message. */
return(1);
};

counter = 0;
while (counter < MAX_LOOP)
{
counter++;

if (!event_flag)
{
/* Do whatever other processing you want. */
;
}
else
{ event_flag = 0;
isc_event_counts(
count_array,
length,
event_buffer,
result_buffer);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector); /* Display error message. */
return(1);
}

API GUIDE 295

 CHAPTER 12 API FUNCTION REFERENCE

for (i=0; i<number_of_stocks; i++)

if (count_array[i])
{
/* The event has been posted. Do whatever is appropriate,
for example, initiating a buy or sell order.
Note: event_names[i] tells the name of the event
corresponding to count_array[i]. */
;
}

isc_que_events(
status_vector,
&database_handle,
&event_id,
length,
event_buffer,
(isc_callback)event_function,
result_buffer);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector); /* Display error message. */
return(1);
}
} /* End of else. */
} /* End of while. */

/* Let InterBase know you no longer want to wait asynchronously. */

isc_cancel_events(
status_vector,
&database_handle,
&event_id);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector); /* Display error message. */
return(1);
}

5HWXUQ9DOXH isc_que_events()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHVVXFFHVV$
QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKHVWDWXVYHFWRU
LVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

296 INTERBASE 5
USING FUNCTION DEFINITIONS

6HH$OVR isc_cancel_events()
isc_event_block()
isc_event_counts()
isc_wait_for_event()
)RUPRUHLQIRUPDWLRQDERXWZULWLQJDQDV\QFKURQRXVHYHQWWUDS $67 IXQFWLRQVHH&KDSWHU
´:RUNLQJZLWK(YHQWVµ

isc_rollback_transaction()
8QGRHVFKDQJHVPDGHE\DWUDQVDFWLRQDQGUHVWRUHVWKHGDWDEDVHWRLWVVWDWHSULRUWRWKHVWDUW
RIWKHVSHFLILHGWUDQVDFWLRQ

6\QWD[ ISC_STATUS isc_rollback_transaction(

ISC_STATUS *status_vector,
isc_tr_handle *trans_handle);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
trans_handle isc_tr_handle * Pointer to a transaction handle whose value has been set by a
previous isc_start_transaction() call; trans_handle returns an
error if NULL

'HVFULSWLRQ isc_rollback_transaction()UROOVEDFNDVSHFLILHGWUDQVDFWLRQFORVHVUHFRUGVWUHDPVIUHHV
V\VWHPUHVRXUFHVDQGVHWVWKHWUDQVDFWLRQKDQGOHWR]HUR,WLVW\SLFDOO\XVHGWRXQGRDOO
GDWDEDVHFKDQJHVPDGHE\DWUDQVDFWLRQZKHQDQHUURURFFXUV
$FDOOWRWKLVIXQFWLRQFDQIDLORQO\LI
g <RXSDVVD18//RULQYDOLGWUDQVDFWLRQKDQGOH
g 7KHWUDQVDFWLRQGHDOWZLWKPRUHWKDQRQHGDWDEDVHDQGDFRPPXQLFDWLRQVOLQNIDLOVGXULQJ
WKHUROOEDFNRSHUDWLRQ,IWKDWKDSSHQVVXEWUDQVDFWLRQVRQWKHUHPRWHQRGHZLOOHQGXSLQ
OLPER<RXPXVWXVHWKHGDWDEDVHPDLQWHQDQFHXWLOLW\WRPDQXDOO\UROOEDFNWKRVH
WUDQVDFWLRQV

([DPSOH 7KHIROORZLQJFDOOUROOVEDFNDWUDQVDFWLRQ
isc_rollback_transaction(status_vector, &trans);

5HWXUQ9DOXH isc_rollback_transaction()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH

API GUIDE 297

 CHAPTER 12 API FUNCTION REFERENCE

7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_commit_transaction()

isc_sqlcode()
7UDQVODWHVDQ,QWHU%DVHHUURUFRGHLQWKHHUURUVWDWXVYHFWRUWRDQ64/HUURUFRGHQXPEHU

6\QWD[ ISC_LONG isc_sqlcode (ISC_STATUS *status_vector);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector

'HVFULSWLRQ isc_sqlcode()VHDUFKHVVWDWXVBYHFWRUIRUDUHSRUWHG64/HUURUDQGLILWILQGVLWWUDQVODWHVWKH
,QWHU%DVHHUURUFRGHQXPEHULQWRDQDSSURSULDWH64/HUURUFRGH7\SLFDOO\WKLVFDOOLVXVHG
WRSRSXODWHDSURJUDPYDULDEOH XVXDOO\FDOOHG64/&2'(IRUSRUWDELOLW\DPRQJ64/
LPSOHPHQWDWLRQV ZLWKDQ64/HUURUQXPEHUIRUXVHLQDQ64/HUURUKDQGOLQJURXWLQH

([DPSOH 7KHIROORZLQJFRGHLOOXVWUDWHVKRZisc_sqlcode()PLJKWEHFDOOHGLQD'64/DSSOLFDWLRQ
#include <ibase.h>
long SQLCODE;
ISC_STATUS status_vector[20];
. . .
if (status_vector[0] == 1 && status_vector[1])
{
SQLCODE = isc_sqlcode(status_vector);
isc_print_sqlerror(SQLCODE, status_vector);
}

5HWXUQ9DOXH ,IVXFFHVVIXOisc_sqlcode()UHWXUQVWKHILUVWYDOLG64/HUURUFRGHGHFRGHGIURPWKH
,QWHU%DVHVWDWXVYHFWRU
,IQRYDOLG64/HUURUFRGHLVIRXQGisc_sqlcode()UHWXUQV²

6HH$OVR isc_interprete()isc_print_sqlerror()isc_print_status()isc_sql_interprete()

298 INTERBASE 5
USING FUNCTION DEFINITIONS

isc_sql_interprete()
%XLOGVDQ64/HUURUPHVVDJHVWULQJDQGVWRUHVLWLQDXVHUGHILQHGEXIIHU

6\QWD[ void isc_sql_interprete(

short SQLCODE,
char *buffer,
short buffer_length);

Parameter Type Description

SQLCODE short Variable containing an SQLCODE value
buffer char * Application buffer into which to store an SQL error message
buffer_length short Length, in bytes, of buffer

'HVFULSWLRQ *LYHQDQ64/&2'(YDOXHOHVVWKDQ]HURisc_sql_interprete()EXLOGVDFRUUHVSRQGLQJ64/
HUURUPHVVDJHVWULQJDQGVWRUHVLWLQDXVHUGHILQHGEXIIHU7KHVL]HRIWKHEXIIHULQE\WHV
PXVWDOVREHSDVVHGWRWKLVIXQFWLRQ
7RGLVSOD\DQ64/HUURUPHVVDJHFRUUHVSRQGLQJWRDQ64/&2'(YDOXHXVH
isc_print_sqlerror()LQVWHDGRIWKLVFDOO

([DPSOH 7KHIROORZLQJFRGHIUDJPHQWLOOXVWUDWHVDFDOOWRisc_sql_interprete()
#include <ibase.h>
long SQLCODE;
char err_buf[256];
. . .
if (status_vector[0] == 1 && status_vector[1])
{
SQLCODE = isc_sqlcode(status_vector);
isc_sql_interprete(SQLCODE, err_buf, sizeof(err_buff));
}

5HWXUQ9DOXH 1RQH

6HH$OVR isc_interprete()isc_print_sqlerror()isc_print_status()isc_sqlcode()

API GUIDE 299

 CHAPTER 12 API FUNCTION REFERENCE

isc_start_multiple()
%HJLQVDQHZWUDQVDFWLRQDJDLQVWPXOWLSOHGDWDEDVHV

6\QWD[ ISC_STATUS isc_start_multiple(

ISC_STATUS *status_vector,
isc_tr_handle *trans_handle,
short db_handle_count,
void *teb_vector_address);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
trans_handle isc_tr_handle * Pointer to a transaction handle whose value has been
set by a previous isc_start_transaction() call;
trans_handle returns an error if NULL
db_handle_count short Number of database handles passed in this call via
transaction existence buffers (TEBs)
teb_vector_address void * Pointer to the TEB

'HVFULSWLRQ &DOOisc_start_multiple()LI\RX
g $UHXVLQJDODQJXDJHWKDWGRHVQRWVXSSRUWDYDULDEOHQXPEHURIDUJXPHQWVLQDIXQFWLRQFDOO
g 'RQRWNQRZKRZPDQ\GDWDEDVHV\RXZDQWWRDWWDFKWRZKHQFRGLQJWKHVWDUWWUDQVDFWLRQ
IXQFWLRQ
isc_start_multiple()SDVVHVLQIRUPDWLRQDERXWHDFKWDUJHWGDWDEDVHWR,QWHU%DVH7KDW
LQIRUPDWLRQLVVWRUHGLQDQDUUD\RIWUDQVDFWLRQH[LVWHQFHEORFNV 7(%V SRLQWHGWRE\WKH
WHEBYHFWRUSDUDPHWHU
WHEBYHFWRULVDSRLQWHUWRDE\WHDUUD\WKDWFRQVLVWVRIFRQVHFXWLYH7(%VRQH7(%IRUHDFK
GDWDEDVHWRFRQQHFWWR(DFK7(%FRQVLVWVRIWKUHHLWHPVDSRLQWHUWRWKHGDWDEDVHKDQGOH
IRUDGDWDEDVHDJDLQVWZKLFKWKHWUDQVDFWLRQVKRXOGUXQWKHOHQJWKLQE\WHVRIWKH
WUDQVDFWLRQSDUDPHWHUEXIIHU 73% IRUWKHGDWDEDVHDQGDSRLQWHUWRWKH73%7KHLWHPVLQ
D7(%FRUUHVSRQGWRWKHLWHPVSDVVHGGLUHFWO\DVSDUDPHWHUVLQFDOOVWR
isc_start_transaction()&SURJUDPPHUVVKRXOGXVHisc_start_transaction()LQVWHDGRI
isc_start_multiple()ZKHQHYHUSRVVLEOHEHFDXVHLWGRHVQRWUHTXLUHVHWWLQJXS7(%V
)RUPRUHLQIRUPDWLRQDERXWHVWDEOLVKLQJ7(%VDQGFDOOLQJisc_start_multiple()VHH
´&DOOLQJLVFBVWDUWBPXOWLSOH  µRQSDJH RI&KDSWHU´:RUNLQJZLWK7UDQVDFWLRQVµ

([DPSOH 7KHIROORZLQJSURJUDPVWDUWVDPXOWLSOHGDWDEDVHWUDQVDFWLRQ

300 INTERBASE 5
USING FUNCTION DEFINITIONS

#include <ibase.h>

typedef struct { /* Define the ISC_TEB structure. */

int *dbb_ptr;
longtpb_len;
char*tpb_ptr;
} ISC_TEB;

ISC_TEB teb_vec[2]; /* Declare the TEB vector. */

ISC_STATUS isc_status[20]; /* Status vector. */

long *db0, *db1, /* Database handle. */
long *trans; /* Transaction handle. */

static char
isc_tpb_0[] = { /* Declare the first transaction parameter
buffer. */
isc_tpb_version3, /* InterBase version. */
isc_tpb_write,/* Read-write access. */
isc_tpb_consistency, /* Serializable. */
isc_tpb_wait, /* Wait on lock. */
isc_tpb_lock_write, 3, /* Reserving IDS for update. */
’I’,’D’,’S’,
isc_tpb_protected},/* Don’t allow other transactions to
write to the table. */

isc_tpb_1[] = { /* Declare the second transaction.*/

/* Parameter buffer. */
isc_tpb_version3, /* InterBase version. */
isc_tpb_write,/* Read-write access. */
isc_tpb_consistency, /* Serializable. */
isc_tpb_wait, /* Wait on lock. */
isc_tpb_lock_write, 3, /* Reserving table OZS for update. */
’O’,’Z’,’S’,
isc_tpb_protected};/* Don’t allow other transactions to
write to the table. */

main()
{
db0 = db1 = 0;
trans = 0;

/* If you can't attach to test_0 database, attach to test_1. */

API GUIDE 301

 CHAPTER 12 API FUNCTION REFERENCE

isc_attach_database(isc_status, 0, "test_0.gdb", &db0, 0,0);

if (isc_status[0] == 1 && isc_status[1])
isc_attach_database(isc_status, 0, "test_1.gdb", &db1, 0,0);

if (db0 && db1)

{ /* Assign database handles, tpb length, and
tbp handle to the teb vectors. */
teb_vec[0].dbb_ptr = &db0;
teb_vec[0].tpb_len = sizeof (isc_tpb_0);
teb_vec[0].tpb_ptr = isc_tpb_0;

teb_vec[1].dbb_ptr = &db1;
teb_vec[1].tpb_len = sizeof (isc_tpb_1);
teb_vec[1].tpb_ptr = isc_tpb_1;

if (isc_start_multiple(isc_status, &trans, 2, teb_vec))

isc_print_status(isc_status);
}

if (trans)
isc_commit_transaction(isc_status, &trans);

if (db0 && !trans)

isc_detach_database(isc_status, &db0);

if (db1 && !(trans && db0))

isc_detach_database(isc_status, &db1);

if (isc_status[0] == 1 && isc_status[1])

isc_print_status(isc_status);
}

5HWXUQ9DOXH isc_start_multiple()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_commit_transaction()
isc_prepare_transaction()isc_prepare_transaction2()
isc_rollback_transaction()isc_start_transaction()

302 INTERBASE 5
USING FUNCTION DEFINITIONS

)RUPRUHLQIRUPDWLRQDERXWWUDQVDFWLRQKDQGOHVVHH´&UHDWLQJWUDQVDFWLRQKDQGOHVµRQ
SDJH RI&KDSWHU´:RUNLQJZLWK7UDQVDFWLRQVµ)RUPRUHLQIRUPDWLRQDERXWFUHDWLQJ
DQGSRSXODWLQJD73%VHH´&UHDWLQJDWUDQVDFWLRQSDUDPHWHUEXIIHUµRQSDJH RI&KDSWHU
´:RUNLQJZLWK7UDQVDFWLRQVµ)RUPRUHLQIRUPDWLRQRQ7(%VVHH´&DOOLQJ
LVFBVWDUWBPXOWLSOH  µRQSDJH RI&KDSWHU´:RUNLQJZLWK7UDQVDFWLRQVµ

isc_start_transaction()
6WDUWVDQHZWUDQVDFWLRQDJDLQVWRQHRUPRUHGDWDEDVHV

6\QWD[ ISC_STATUS isc_start_transaction(

ISC_STATUS *status_vector,
isc_tr_handle *trans_handle,
short db_handle_count,
isc_db_handle *db_handle,
unsigned short tpb_length,
char *tpb_address,
[isc_db_handle *db_handle,
unsigned short tpb_length,
char *tpb_address ...]);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
trans_handle isc_tr_handle * Pointer to a transaction handle whose value has been set
by a previous isc_start_transaction() call; trans_handle
returns an error if NULL
db_handle_count short Number of database handles passed in this call
db_handle isc_db_handle * Pointer to a database handle set by a previous call to
isc_attach_database(); the handle identifies the
database against which the events are expected to be
posted
db_handle returns an error in status_vector if it is NULL
tpb_length unsigned short Length of the transaction parameter buffer (TPB)
tpb_address char * Pointer to the TPB

'HVFULSWLRQ isc_start_transaction()VWDUWVDQHZWUDQVDFWLRQDJDLQVWRQHRUPRUHGDWDEDVHVVSHFLILHGDV
GDWDEDVHKDQGOHV

API GUIDE 303

 CHAPTER 12 API FUNCTION REFERENCE

Note ,I\RXKDYHDYDULDEOHQXPEHURIGDWDEDVHVWRXSGDWHRUDUHXVLQJDODQJXDJHWKDWGRHV
QRWVXSSRUWDYDULDEOHQXPEHURIDUJXPHQWVLQDIXQFWLRQFDOOXVH isc_start_multiple()
LQVWHDGRIisc_start_transaction()
$VLQJOHWUDQVDFWLRQFDQDFFHVVPXOWLSOHGDWDEDVHV7KLVIXQFWLRQSDVVHVLQIRUPDWLRQDERXW
HDFKGDWDEDVHLWDFFHVVHVDQGWKHFRQGLWLRQVRIDFFHVVIRUWKDWGDWDEDVHLQDWUDQVDFWLRQ
SDUDPHWHUEXIIHU 73% 7KH73%LVDYDULDEO\VL]HGYHFWRURIE\WHVGHFODUHGDQGSRSXODWHGE\
WKHSURJUDP,WFRQWDLQVLQIRUPDWLRQGHVFULELQJLQWHQGHGWUDQVDFWLRQEHKDYLRUVXFKDVLWV
DFFHVVDQGORFNPRGHV
isc_start_transaction()FDQVWDUWDWUDQVDFWLRQDJDLQVWXSWRGDWDEDVHV<RXPXVWSDVVD
GDWDEDVHKDQGOHDQGD73%IRUHDFKUHIHUHQFHGGDWDEDVH,I\RXZDQWWRXVHGHIDXOWVIRUWKH
WUDQVDFWLRQVHWWSEBOHQJWKWR]HUR,QWKLVFDVHWSEBYHFWRULVD18//SRLQWHU

([DPSOH 7KHIROORZLQJSURJUDPLQFOXGHVDFDOOWRWKHVWDUWWUDQVDFWLRQIXQFWLRQ
#include <ibase.h>

long
isc_status[20], /* Status vector. */
*db, /* Database handle. */
*trans, /* Transaction handle. */

static char
isc_tpb_0[] = {
isc_tpb_version3, /* InterBase version. */
isc_tpb_write,/* Read-write access. */
isc_tpb_consistency, /* Consistency-mode transaction. */
isc_tpb_wait, /* Wait on lock. */
isc_tpb_lock_write, 3, /* Reserving IDS table for update. */
"I","D","S",
isc_tpb_protected};/* Don’t allow other transactions to
write against this table. */
main()
{
db = trans = 0;
isc_attach_database(isc_status, 0, "test.gdb", &db, 0,0);

if (db)
{
isc_start_transaction(
isc_status, &trans, 1, &db,
sizeof(isc_tpb_0), isc_tpb_0);
if (isc_status[0] == 1 && isc_status[1])
isc_print_status(isc_status);

304 INTERBASE 5
USING FUNCTION DEFINITIONS

}
if (trans)
isc_commit_transaction(isc_status, &trans);

if (db && !trans)

isc_detach_database(isc_status, &db);

if (status_vector[0] == 1 && status_vector[1])

isc_print_status(isc_status);
}

5HWXUQ9DOXH isc_start_transaction()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_commit_transaction()
isc_prepare_transaction()
isc_prepare_transaction2()
isc_rollback_transaction()isc_start_multiple()
)RUPRUHLQIRUPDWLRQDERXWWUDQVDFWLRQKDQGOHVVHH´&UHDWLQJWUDQVDFWLRQKDQGOHVµRQ
SDJH RI&KDSWHU´:RUNLQJZLWK7UDQVDFWLRQVµ)RUPRUHLQIRUPDWLRQDERXWFUHDWLQJ
DQGSRSXODWLQJD73%VHH´&UHDWLQJDWUDQVDFWLRQSDUDPHWHUEXIIHUµRQSDJH RI&KDSWHU
´:RUNLQJZLWK7UDQVDFWLRQVµ

API GUIDE 305

 CHAPTER 12 API FUNCTION REFERENCE

isc_transaction_info()
5HWXUQVLQIRUPDWLRQDERXWWKHVSHFLILHGQDPHGWUDQVDFWLRQ

6\QWD[ ISC_STATUS isc_transaction_info(

ISC_STATUS *status_vector,
isc_tr_handle *trans_handle,
short item_list_buffer_length,
char *item_list_buffer,
short result_buffer_length,
char *result_buffer);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
trans_handle isc_tr_handle * Pointer to a transaction handle whose value has been
set by a previous isc_start_transaction() call;
trans_handle returns an error if NULL
item_list_buffer_length short Number of bytes in the item-list buffer
item_list_buffer char * Pointer to the item-list buffer
result_buffer_length short Number of bytes in the result buffer
result_buffer char * Pointer to the result buffer

'HVFULSWLRQ isc_transaction_info()UHWXUQVLQIRUPDWLRQQHFHVVDU\IRUNHHSLQJWUDFNRIWUDQVDFWLRQ,'V
7KLVFDOOLVXVHGLQWHUQDOO\E\isc_prepare_transaction()<RXVKRXOGQRWQHHGWRXVHLWLQ
\RXURZQDSSOLFDWLRQV
<RXFDQH[SOLFLWO\UHWULHYHLQIRUPDWLRQDERXWWKHWUDQVDFWLRQ,'E\LQFOXGLQJWKHIROORZLQJ
FRQVWDQWLQWKHLWHPOLVWEXIIHUZKHUHWKHWUDQVDFWLRQLWHPVDERXWZKLFK\RXZDQW
LQIRUPDWLRQDUHOLVWHG

Item Purpose Size of next value Value

isc_info_tra_id Determine the transaction ID 2 bytes transaction ID
TABLE 12.20 Transaction information request item

isc_transaction_info()XVHVWZREXIIHUVGHILQHGLQWKHFDOOLQJSURJUDPWKHLWHPOLVWEXIIHU
ZKLFKOLVWVWUDQVDFWLRQLWHPVDERXWZKLFK\RXZDQWLQIRUPDWLRQDQGDUHVXOWEXIIHUZKHUHWKH
LQIRUPDWLRQUHTXHVWHGLVUHSRUWHG

306 INTERBASE 5
USING FUNCTION DEFINITIONS

7RGHILQHWKHLWHPOLVWEXIIHULQFOXGHWKHSDUDPHWHUVLWHPBOLVWBEXIIHUBOHQJWKDQG
LWHPBOLVWBEXIIHUBDGGUHVV7KHLWHPOLVWEXIIHULVDUHJXODUE\WHYHFWRUZLWKQRVWUXFWXUH
7RGHILQHWKHUHVXOWEXIIHULQFOXGHWKHSDUDPHWHUVUHVXOWBEXIIHUBOHQJWKDQGUHVXOWBEXIIHUBDGGUHVV
7KHVHSDUDPHWHUVVSHFLI\WKHOHQJWKDQGDGGUHVVRIDEXIIHUZKHUHWKH,QWHU%DVHHQJLQHZLOO
SODFHWKHUHWXUQYDOXHVIURPWKHIXQFWLRQFDOO
7KHYDOXHVUHWXUQHGWRWKHUHVXOWEXIIHUDUHXQDOLJQHGFOXVWHUVRIJHQHULFELQDU\QXPEHUV
)XUWKHUPRUHDOOQXPEHUVDUHUHSUHVHQWHGLQDJHQHULFIRUPDWZLWKWKHOHDVWVLJQLILFDQWE\WH
ILUVWDQGWKHPRVWVLJQLILFDQWE\WHODVW6LJQHGQXPEHUVKDYHWKHVLJQLQWKHODVWE\WH&RQYHUW
WKHQXPEHUVWRDGDWDW\SHQDWLYHWR\RXUV\VWHPEHIRUHLQWHUSUHWLQJWKHP
,Q\RXUFDOOLQFOXGHWKHLWHPVSHFLI\LQJWKHWUDQVDFWLRQ,'LVFBLQIRBWUDBLG,QWHU%DVHUHWXUQV
WKHWUDQVDFWLRQ,'LQWKHUHVXOWEXIIHU,QDGGLWLRQWRWKHLQIRUPDWLRQ,QWHU%DVHUHWXUQVLQ
UHVSRQVHWRDUHTXHVW,QWHU%DVHFDQDOVRUHWXUQRQHRUPRUHRIWKHIROORZLQJVWDWXVPHVVDJHV
WRWKHUHVXOWEXIIHU(DFKVWDWXVPHVVDJHLVRQHXQVLJQHGE\WHLQOHQJWK

Item Description
isc_info_end End of the messages
isc_info_truncated Result buffer is too small to hold any more requested information
isc_info_error Requested information is unavailable; check the status vector for an error
code and message
TABLE 12.21 Status message return items

7KHIXQFWLRQUHWXUQYDOXHLQGLFDWHVRQO\WKDW,QWHU%DVHDFFHSWHGWKHUHTXHVWIRULQIRUPDWLRQ
,WGRHVQRWPHDQWKDWLWXQGHUVWRRGWKHUHTXHVWRUWKDWLWVXSSOLHGDOORIWKHUHTXHVWHG
LQIRUPDWLRQ<RXUDSSOLFDWLRQPXVWLQWHUSUHWWKHFRQWHQWVRIWKHUHVXOWEXIIHUIRUGHWDLOV
DERXWWKHWUDQVDFWLRQ

([DPSOH 7KHIROORZLQJFRGHIUDJPHQWJHWVLQIRUPDWLRQDERXWDWUDQVDFWLRQ
static char /* Declare item-list buffer. */
tra_items[] =
{isc_info_tra_id};
/* Declare result buffer. */
CHAR tra_info[32];

isc_transaction_info(status_vector,
&tr_handle,
sizeof (tra_items), /* Length of item-list buffer. */
&tra_items, /* Address of item-list buffer. */

API GUIDE 307

 CHAPTER 12 API FUNCTION REFERENCE

sizeof (tra_info), /* Length of result buffer. */

&tra_info); /* Address of result buffer. */
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector);
return(1);
}

5HWXUQ9DOXH isc_transaction_info()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH
7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_start_transaction()

isc_vax_integer()
5HYHUVHVWKHE\WHRUGHURIDQLQWHJHU

6\QWD[ ISC_LONG isc_vax_integer(

char *buffer,
short length);

Parameter Type Description

buffer char * Pointer to the integer to convert
length short Length, in bytes, of the integer to convert
Valid lengths are 1, 2, and 4 bytes

'HVFULSWLRQ isc_vax_integer()UHYHUVHVWKHE\WHRUGHURIDQLQWHJHUVSHFLILHGLQEXIIHUDQGUHWXUQVWKH
QHZO\RUGHUHGYDOXH
$W\SLFDOXVHIRUWKLVIXQFWLRQLVWRFRQYHUWLQWHJHUYDOXHVSDVVHGLQWRDGDWDEDVHSDUDPHWHU
EXIIHUWRDIRUPDWZKHUHWKHOHDVWVLJQLILFDQWE\WHPXVWEHILUVWDQGWKHPRVWVLJQLILFDQWE\WH
ODVW,Q,QWHU%DVHLQWHJHUYDOXHVPXVWEHUHSUHVHQWHGLQLQSXWSDUDPHWHUEXIIHUV IRUH[DPSOH
WKH'3% DQGDUHUHWXUQHGLQUHVXOWEXIIHUVLQDJHQHULFIRUPDWZKHUHWKHOHDVWVLJQLILFDQW
E\WHLVILUVWDQGWKHPRVWVLJQLILFDQWE\WHODVWisc_vax_integer()LVXVHGWRFRQYHUWLQWHJHUV
WRDQGIURPWKLVIRUPDW

308 INTERBASE 5
USING FUNCTION DEFINITIONS

([DPSOH 7KHIROORZLQJFRGHIUDJPHQWFRQYHUWVDE\WHYDOXHVWRUHGLQDFKDUDFWHUEXIIHUWKDWLVWKH
UHVXOWEXIIHUUHWXUQHGE\DIXQFWLRQVXFKDVisc_database_info()
#include <ibase.h>
char *p;
. . .
for(p = res_buffer; *p != isc_info_end;)
{
/* Read item type of next cluster in the result buffer. */
item = *p++;
/* Read length of next value in result buffer, and convert. */
len = isc_vax_integer(p, 2);
p += len;
/* Now process the actual value, len bytes in size. */
. . .
}

5HWXUQ9DOXH isc_vax_integer()DOZD\VUHWXUQVDE\WHUHYHUVHGORQJLQWHJHUYDOXH

6HH$OVR isc_attach_database()isc_database_info()

isc_version()
5HWXUQVGDWDEDVHLPSOHPHQWDWLRQDQGYHUVLRQLQIRUPDWLRQ

6\QWD[ int isc_version(

isc_db_handle *db_handle,
isc_callback function_name,
void *user_arg);

Parameter Type Description

db_handle isc_db_handle * Pointer to a database handle set by a previous call to
isc_attach_database()
db_handle returns an error in status_vector if it is NULL
function_name isc_callback Pointer to a function to call with the relevant information;
passing a NULL pointer in C programs calls printf()
user_arg void * An application-specified parameter to pass as the first of two
arguments to function_name

API GUIDE 309

 CHAPTER 12 API FUNCTION REFERENCE

'HVFULSWLRQ isc_version()GHWHUPLQHVWKHGDWDEDVHLPSOHPHQWDWLRQDQGRQGLVNVWUXFWXUH 2'6 

YHUVLRQQXPEHUVIRUWKHGDWDEDVHVSHFLILHGE\GEBKDQGOH,WSDVVHVWKLVLQIRUPDWLRQLQWZR
VHSDUDWHFDOOVWRWKHFDOOEDFNIXQFWLRQSRLQWHGWRE\IXQFWLRQBQDPH
IXQFWLRQBQDPHVKRXOGSRLQWWRDQDSSOLFDWLRQIXQFWLRQWKDWWDNHVWZRDUJXPHQWVDYRLGSRLQWHU
XVHUBDUJDQGDFKDUSRLQWHU$SSOLFDWLRQVFDQSDVVDQ\NLQGRISDUDPHWHUGHVLUHGLQXVHUBDUJ
isc_version()PDNHVWZRFDOOVWRIXQFWLRQBQDPH)LUVWLWGHWHUPLQHVWKHGDWDEDVH
LPSOHPHQWDWLRQQXPEHUEXLOGVDVWULQJFRQWDLQLQJWKHLQIRUPDWLRQDQGFDOOVIXQFWLRQBQDPH
ZLWKXVHUBDUJDQGDSRLQWHUWRWKHVWULQJFRQWDLQLQJWKHLPSOHPHQWDWLRQQXPEHULQWKH
IROORZLQJIRUPDW
<implementation>(<class>), version "<version>"
ZKHUH
g LPSOHPHQWDWLRQ!LVDWH[WVWULQJVXFKDV´,QWHU%DVH17µ
g FODVV!LVDWH[WVWULQJVSHFLI\LQJWKHLPSOHPHQWDWLRQFODVVVXFKDV´DFFHVVPHWKRGµ
g YHUVLRQ!LVDYHUVLRQLGHQWLILFDWLRQVWULQJVXFKDV´µ
7KHFDOOEDFNIXQFWLRQVSHFLILHGE\IXQFWLRQBQDPHLVIUHHWRGRZLWKWKLVLQIRUPDWLRQZKDWLW
SOHDVHV
$IWHUWKHFDOOEDFNIXQFWLRQUHWXUQVFRQWUROWRisc_version()isc_version()EXLOGVDQHZ
VWULQJFRQWDLQLQJWKH2'6PDMRUDQGPLQRUYHUVLRQQXPEHUVWKHQFDOOVIXQFWLRQBQDPHD
VHFRQGWLPHZLWKXVHUBDUJDQGDSRLQWHUWRWKHVWULQJFRQWDLQLQJWKH2'6YHUVLRQQXPEHULQ
WKHIROORZLQJIRUPDW
on disk structure version <ods_major_num>.<ods_minor_num>
ZKHUH
g RGVBPDMRUBQXP!LVWKHPDMRU2'6QXPEHU'DWDEDVHVZLWKGLIIHUHQWPDMRUYHUVLRQ
QXPEHUVKDYHGLIIHUHQWSK\VLFDOOD\RXWVRQGLVNDQGDUHLQFRPSDWLEOHZLWKRQHDQRWKHU$
GDWDEDVHHQJLQHFDQRQO\DFFHVVGDWDEDVHVZLWKDSDUWLFXODU2'6PDMRUQXPEHU
g RGVBPLQRUBQXP!LVWKHPLQRU2'6QXPEHU'LIIHUHQFHVLQWKHPLQRU2'6QXPEHUEXWQRW
WKHPDMRURQHLQGLFDWHDQRQVWUXFWXUDOFKDQJHWKDWVWLOOSHUPLWVDFFHVVE\DQ\GDWDEDVHHQJLQH
WKDWUHFRJQL]HVWKHPDMRUYHUVLRQQXPEHU

7,3 ,ID18//SRLQWHULVSDVVHGIRUIXQFWLRQBQDPHisc_version()VHWVIXQFWLRQBQDPHWRSRLQWWR
WKH&printf()IXQFWLRQ

([DPSOHV 7KHIROORZLQJFRGHIUDJPHQWFDOOVisc_version()ZLWKD18//FDOOEDFNIXQFWLRQ
#include <ibase.h>
. . .
int ret;
. . .
ret = isc_version(&db1, NULL, "\t%s\n");

310 INTERBASE 5
USING FUNCTION DEFINITIONS

5HWXUQ9DOXH ,IVXFFHVVIXOisc_version()UHWXUQV2WKHUZLVHLWUHWXUQVDQRQ]HURYDOXH

6HH$OVR isc_database_info()

isc_wait_for_event()
:DLWVV\QFKURQRXVO\XQWLORQHRIDVSHFLILHGJURXSRIHYHQWVLVSRVWHG
Note 7KHisc_wait_for_event()IXQFWLRQZDVFDOOHGgds_$event_wait()LQ,QWHU%DVH,W
LVWKHUHIRUHWKHRQO\IXQFWLRQWKDWFDQ·WEHWUDQVODWHGIURPQRPHQFODWXUHWRDOOODWHU
YHUVLRQVE\UHSODFLQJgds_$ ZLWKisc_

6\QWD[ ISC_STATUS isc_wait_for_event(

ISC_STATUS *status_vector,
isc_db_handle *db_handle,
short length,
char *event_buffer,
char *result_buffer);

Parameter Type Description

status_vector ISC_STATUS * Pointer to the error status vector
db_handle isc_db_handle * Pointer to a database handle set by a previous call to
isc_attach_database(); the handle identifies the database
against which the events are expected to be posted
db_handle returns an error in status_vector if it is NULL
length short Length of the event parameter buffers, returned by the
isc_event_block() call which allocated them
event_buffer char * Pointer to the event parameter buffer that specifies the current
counts of the events to be waited on; this buffer should have
been initially allocated and filled in by a call to
isc_event_block()
result_buffer char * Pointer to the event parameter buffer to be filled in with
updated event counts as a result of this function call; this
buffer should have been initially allocated by a call to
isc_event_block()

'HVFULSWLRQ isc_wait_for_event()LVXVHGWRZDLWV\QFKURQRXVO\XQWLORQHRIDVSHFLILHGJURXSRIHYHQWV
LVSRVWHG&RQWUROLVQRWUHWXUQHGWRWKHFDOOLQJDSSOLFDWLRQXQWLORQHRIWKHVSHFLILHGHYHQWV
RFFXUV

API GUIDE 311

 CHAPTER 12 API FUNCTION REFERENCE

(YHQWVWRZDLWRQDUHVSHFLILHGLQHYHQWBEXIIHUZKLFKVKRXOGKDYHEHHQLQLWLDOO\DOORFDWHGDQG
ILOOHGLQE\DSUHYLRXVFDOOWRisc_event_block()
:KHQRQHRIWKHVHHYHQWVLVSRVWHGisc_wait_for_event() ILOOVLQUHVXOWBEXIIHUZLWKGDWDWKDW
H[DFWO\FRUUHVSRQGVWRWKDWLQWKHLQLWLDOEXIIHUH[FHSWWKDWWKHHYHQWFRXQWVZLOOEHWKH
XSGDWHGRQHV&RQWUROWKHQUHWXUQVIURP isc_wait_for_event()WRWKHFDOOLQJDSSOLFDWLRQ
7KHDSSOLFDWLRQVKRXOGWKHQFDOOisc_event_counts()WRGHWHUPLQHZKLFKHYHQWZDVSRVWHG
Note 7RUHTXHVWDV\QFKURQRXVQRWLILFDWLRQRIHYHQWSRVWLQJVXVH isc_que_events()LQVWHDGRI
isc_wait_for_event()<RXPXVWXVHDV\QFKURQRXVQRWLILFDWLRQVLQ0LFURVRIW:LQGRZV
DSSOLFDWLRQVRUZKHUHYHUDSURFHVVPXVWQRWVWRSSURFHVVLQJ

([DPSOH 7KHIROORZLQJSURJUDPIUDJPHQWLOOXVWUDWHVDFDOOWRisc_wait_for_event()WRZDLWIRUD
SRVWLQJRIDQ\RIWKHHYHQWVQDPHG´'(&µ´+3µRU´681µ
#include <ibase.h>
#define number_of_stocks 3;

char *event_buffer, *result_buffer;

short length;

length = (short)isc_event_block(
&event_buffer,
&result_buffer,
number_of_stocks,
"DEC", "HP", "SUN");

isc_wait_for_event(
status_vector,
&database_handle,
length, /* Returned from isc_event_block(). */
event_buffer,
result_buffer);
if (status_vector[0] == 1 && status_vector[1])
{
isc_print_status(status_vector); /* Display error message. */
return(1);
}

/* Call isc_event_counts() to compare event counts in the buffers and thus

determine which event(s) were posted. */

5HWXUQ9DOXH isc_wait_for_event()UHWXUQVWKHVHFRQGHOHPHQWRIWKHVWDWXVYHFWRU=HURLQGLFDWHV
VXFFHVV$QRQ]HURYDOXHLQGLFDWHVDQHUURU)RU,QWHU%DVHHUURUVWKHILUVWHOHPHQWRIWKH
VWDWXVYHFWRULVVHWWRDQGWKHVHFRQGHOHPHQWLVVHWWRDQ,QWHU%DVHHUURUFRGH

312 INTERBASE 5
USING FUNCTION DEFINITIONS

7RFKHFNIRUDQ,QWHU%DVHHUURUH[DPLQHWKHILUVWWZRHOHPHQWVRIWKHVWDWXVYHFWRUGLUHFWO\
)RUPRUHLQIRUPDWLRQDERXWH[DPLQLQJWKHVWDWXVYHFWRUVHH&KDSWHU´+DQGOLQJ(UURU
&RQGLWLRQVµ

6HH$OVR isc_event_block()isc_que_events()

API GUIDE 313

 APPENDIX

InterBase Document
AppendixA
A
Conventions

7KLVDSSHQGL[GHVFULEHVWKH,QWHU%DVHGRFXPHQWDWLRQVHWWKHSULQWLQJFRQYHQWLRQVXVHG
WRGLVSOD\LQIRUPDWLRQLQWH[WDQGLQFRGHH[DPSOHVDQGFRQYHQWLRQVIRUQDPLQJGDWDEDVH
REMHFWVDQGILOHVLQDSSOLFDWLRQV

315
 APPENDIX A INTERBASE DOCUMENT CONVENTIONS

The InterBase documentation set

7KH,QWHU%DVHGRFXPHQWDWLRQVHWLVDQLQWHJUDWHGSDFNDJHGHVLJQHGIRUDOOOHYHOVRIXVHUV,W
FRQVLVWVRIILYHSULQWHGERRNV(DFKRIWKHVHERRNVLVDOVRSURYLGHGLQ$GREH$FUREDW3')
IRUPDWDQGLVDFFHVVLEOHRQOLQHWKURXJKWKH+HOSPHQX,I$GREH$FUREDWLVQRWDOUHDG\
LQVWDOOHGRQ\RXUV\VWHP\RXFDQILQGLWRQWKH,QWHU%DVHGLVWULEXWLRQ&'520RUDW
KWWSZZZDGREHFRPSURGLQGH[DFUREDWUHDGVWHSKWPO$FUREDWLVDYDLODEOHIRU:LQGRZV17
:LQGRZVDQGPRVWIODYRUVRI81,;:LQGRZVXVHUVDOVRKDYHKHOSDYDLODEOHWKURXJKWKH
:LQ+HOSV\VWHP

Book Description
Operations Guide Provides an introduction to InterBase and an explanation of tools and
procedures for performing administrative tasks on databases and database
servers. Also includes full reference on InterBase utilities, including isql, gbak,
Server Manager for Windows, and others.
Data Definition Guide Explains how to create, alter, and delete database objects through ISQL.
Language Reference Describes SQL and DSQL syntax and usage.
Programmer’s Guide Describes how to write embedded SQL and DSQL database applications in a
host language, precompiled through gpre.
API Guide Explains how to write database applications using the InterBase API.
TABLE A.1 Books in the InterBase 5.1 documentation set

316 INTERBASE 5
PRINTING CONVENTIONS

Printing conventions
7KH,QWHU%DVHGRFXPHQWDWLRQVHWXVHVYDULRXVW\SRJUDSKLFFRQYHQWLRQVWRLGHQWLI\REMHFWV
DQGV\QWDFWLFHOHPHQWV
7KHIROORZLQJWDEOHOLVWVW\SRJUDSKLFFRQYHQWLRQVXVHGLQWH[WDQGSURYLGHVH[DPSOHVRIWKHLU
XVH

Convention Purpose Example

UPPERCASE SQL keywords, SQL functions, and names of all The following SELECT statement retrieves data from the
database objects such as tables, columns, CITY column in the CITIES table.
indexes, and stored procedures.
italic New terms, emphasized words, file names, and The isc4.gdb security database is not accessible
host- language variables. without a valid user name and password.
bold Utility names, user-defined and host-language Use gbak to back up and restore a database.
function names. Function names are always
Use the datediff() function to calculate the number of
followed by parentheses to distinguish them days between two dates.
from utility names.
TABLE A.2 Text conventions

API GUIDE 317

 APPENDIX A INTERBASE DOCUMENT CONVENTIONS

Syntax conventions
7KHIROORZLQJWDEOHOLVWVWKHFRQYHQWLRQVXVHGLQV\QWD[VWDWHPHQWVDQGVDPSOHFRGHDQG
SURYLGHVH[DPSOHVRIWKHLUXVH

Convention Purpose Example

UPPERCASE Keywords that must be typed exactly as SET TERM !!;
they appear when used.
italic Parameters that cannot be broken into CREATE GENERATOR name;
smaller units. For example, a table name
cannot be subdivided.
<italic> Parameters in angle brackets that can be WHILE (<condition>) DO <compound_statement>
broken into smaller syntactic units.
[] Optional syntax: you do not need to CREATE [UNIQUE][ASCENDING|DESCENDING]
include anything that is enclosed in square
brackets.
{} One of the enclosed options must be {SMALLINT | INTEGER | FLOAT | DOUBLE PRECISION}
included in actual statement use. If the
contents are separated by a pipe symbol
(|), you must choose only one.
| You can choose only one of a group whose SET {DATABASE | SCHEMA}
elements are separated by this pipe SELECT [DISTINCT |ALL]
symbol.
When objects separated by this symbol
occur within curly brackets, you must
choose one; when they are within square
brackets you can choose one or none.
... The clause in brackets with this symbol can (<col> [,<col>…])
be repeated as many times as necessary.
TABLE A.3 Syntax conventions

318 INTERBASE 5
 APPENDIX

Data Structures
AppendixB
B
7KLVDSSHQGL[GRFXPHQWVWKHGDWDVWUXFWXUHVFRPSLOHWLPHFRQVWDQWVSDUDPHWHUEXIIHUV
DQGLQIRUPDWLRQEXIIHUVXWLOL]HGLQ,QWHU%DVH$3,DSSOLFDWLRQV
7KLVLQIRUPDWLRQDOVRDSSHDUVWKURXJKRXWWKHUHVWRIWKLV$3,*XLGHEXWLVFRQVROLGDWHGKHUH
DVDFRQYHQLHQFH6HHRWKHUVHFWLRQVRIWKLVPDQXDOIRUPRUHLQIRUPDWLRQ
$OOWKHVWUXFWXUHVDQGFRPSLOHWLPHFRQVWDQWVPHQWLRQHGDUHGHILQHGLQWKHLEDVHKKHDGHUILOH
,WHPVDUHGRFXPHQWHGDOSKDEHWLFDOO\DVIROORZV
g $UUD\GHVFULSWRU
g %OREGHVFULSWRU
g %ORELQIRUPDWLRQLWHPOLVWEXIIHUDQGUHVXOWEXIIHU
g %ORESDUDPHWHUEXIIHU
g 'DWDEDVHLQIRUPDWLRQUHTXHVWEXIIHUDQGUHVXOWEXIIHU
g 'DWDEDVHSDUDPHWHUEXIIHU
g 64/GDWDW\SHPDFURFRQVWDQWV
g 6WDWXVYHFWRU
g 7UDQVDFWLRQSDUDPHWHUEXIIHU
g ;64/'$DQG;64/9$5VWUXFWXUHV

319
 APPENDIX B DATA STRUCTURES

Array descriptor
$QDUUD\GHVFULSWRU,6&B$55$<B'(6&LVDVWUXFWXUHGHILQHGLQWKHLEDVHKKHDGHUILOHDV
typedef struct {
unsigned char array_desc_dtype;
char array_desc_scale;
unsigned short array_desc_length;
char array_desc_field_name [32];
char array_desc_relation_name [32];
short array_desc_dimensions;
short array_desc_flags;
ISC_ARRAY_BOUND array_desc_bounds [16];
} ISC_ARRAY_DESC;

,6&B$55$<B%281'LVGHILQHGDV
typedef struct {
short array_bound_lower; /* lower bound */
short array_bound_upper; /* upper bound */
} ISC_ARRAY_BOUND;

Field Description
array_desc_dtype Datatype (see below)
array_desc_scale Scale for numeric datatypes
array_desc_length Length in bytes of each array element
array_desc_field_name NULL-terminated column name
array_desc_relation_name NULL-terminated relation name
array_desc_dimensions Number of array dimensions
array_desc_flags Specifies whether array is to be accessed in row- major or column-major
order
• 0: row-major
• 1: column-major
array_desc_bounds Lower and upper bounds for each dimension
TABLE B.1 Array descriptor fields

320 INTERBASE 5
DATATYPES FOR ARRAY DESCRIPTORS

Datatypes for array descriptors

7KHDUUD\BGHVFBGW\SHILHOGRIDQDUUD\GHVFULSWRUPXVWEHH[SUHVVHGDVRQHRIWKHGDWDW\SHVLQ
WKHIROORZLQJWDEOH

array_desc_dtype
value Corresponding InterBase datatype
blr_text CHAR

blr_text2 CHAR

blr_short SMALLINT

blr_long INTEGER

blr_quad ISC_QUAD structure

blr_float FLOAT

blr_double DOUBLE PRECISION

blr_date DATE

blr_varying VARCHAR

blr_varying2 VARCHAR

blr_blob_id ISC_QUAD structure

blr_cstring NULL-terminated string

blr_cstring2 NULL-terminated string

TABLE B.2 Datatypes for array descriptors

Blob descriptor
$%OREGHVFULSWRULVGHILQHGDV
typedef struct {
short blob_desc_subtype;
short blob_desc_charset;
short blob_desc_segment_size;
unsigned char blob_desc_field_name [32];
unsigned char blob_desc_relation_name [32];

API GUIDE 321

 APPENDIX B DATA STRUCTURES

} ISC_BLOB_DESC;

Field Description
blob_desc_subtype Type of Blob data
0: unstructured
1: TEXT
negative integer between –1 and –32678: user-defined subtype
blob_desc_charset Character set (see below)
blob_desc_segment_size Segment size
blob_desc_field_name NULL-terminated column name

blob_desc_relation_name NULL-terminated table name

TABLE B.3 Blob descriptor fields

Character sets
,QWHU%DVHVXSSRUWVDQXPEHURIFKDUDFWHUVHWV)RUDOLVWRIWKHFKDUDFWHUVHWVVXSSRUWHGDQG
WKHFKDUDFWHUVHWYDOXHWKDWPXVWEHHQWHUHGLQWKHEOREBGHVFBFKDUVHWILHOGRID%OREGHVFULSWRU
VHHWKH'DWD'HILQLWLRQ*XLGH

Blob information buffers

7KHisc_blob_info()FDOOHQDEOHVDQDSSOLFDWLRQWRTXHU\IRU%ORELQIRUPDWLRQVXFKDVWKH
WRWDOQXPEHURIVHJPHQWVLQWKH%ORERUWKHOHQJWKRIWKHORQJHVWVHJPHQW
isc_blob_info()UHTXLUHVWZRDSSOLFDWLRQSURYLGHGEXIIHUVDQLWHPOLVWEXIIHUZKHUHWKH
DSSOLFDWLRQVSHFLILHVWKHLQIRUPDWLRQLWQHHGVDQGDUHVXOWEXIIHUZKHUH,QWHU%DVHUHWXUQVWKH
UHTXHVWHGLQIRUPDWLRQ$QDSSOLFDWLRQSRSXODWHVWKHLWHPOLVWEXIIHUZLWKLQIRUPDWLRQSULRU
WRFDOOLQJisc_blob_info(),QWHU%DVHUHWXUQVLQIRUPDWLRQLQWKHUHVXOWEXIIHU,I,QWHU%DVH
DWWHPSWVWRSDVVEDFNPRUHLQIRUPDWLRQWKDQFDQILWLQWKHUHVXOWEXIIHULWSXWVWKHYDOXH
LVFBLQIRBWUXQFDWHGGHILQHGLQLEDVHKLQWKHILQDOE\WHRIWKHUHVXOWEXIIHU

322 INTERBASE 5
BLOB DESCRIPTOR

4 ,WHPOLVWEXIIHU
7KHLWHPOLVWEXIIHULVDE\WHYHFWRULQWRZKLFKLVSODFHGDVHTXHQFHRIE\WHYDOXHVRQHSHU
UHTXHVWHGLWHPRILQIRUPDWLRQ(DFKE\WHLVDQLWHPW\SHVSHFLI\LQJWKHNLQGRILQIRUPDWLRQ
GHVLUHG&RPSLOHWLPHFRQVWDQWVIRUDOOLWHPW\SHVDUHGHILQHGLQLEDVHK
#define isc_info_blob_num_segments 4
#define isc_info_blob_max_segment 5
#define isc_info_blob_total_length 6
#define isc_info_blob_type 7

4 5HVXOWEXIIHU
7KHUHVXOWEXIIHULVDE\WHYHFWRULQZKLFK,QWHU%DVHUHWXUQVDVHULHVRIFOXVWHUVRILQIRUPDWLRQ
RQHSHULWHPUHTXHVWHG(DFKFOXVWHUFRQVLVWVRIWKUHHSDUWV
 $RQHE\WHLWHPW\SH(DFKLVWKHVDPHDVRQHRIWKHLWHPW\SHVLQWKHLWHPOLVW
EXIIHU
 $E\WHQXPEHUVSHFLI\LQJWKHQXPEHURIE\WHVWKDWIROORZLQWKHUHPDLQGHURI
WKHFOXVWHU
 $YDOXHVWRUHGLQDYDULDEOHQXPEHURIE\WHVZKRVHLQWHUSUHWDWLRQGHSHQGVRQ
WKHLWHPW\SH
$FDOOLQJSURJUDPLVUHVSRQVLEOHIRULQWHUSUHWLQJWKHFRQWHQWVRIWKHUHVXOWEXIIHUDQGIRU
GHFLSKHULQJHDFKFOXVWHUDVDSSURSULDWH
7KHFOXVWHUVUHWXUQHGWRWKHUHVXOWEXIIHUDUHQRWDOLJQHG)XUWKHUPRUHDOOQXPEHUVDUH
UHSUHVHQWHGLQDJHQHULFIRUPDWZLWKWKHOHDVWVLJQLILFDQWE\WHILUVWDQGWKHPRVWVLJQLILFDQW
E\WHODVW6LJQHGQXPEHUVKDYHWKHVLJQLQWKHODVWE\WH&RQYHUWWKHQXPEHUVWRDGDWDW\SH
QDWLYHWR\RXUV\VWHPLIQHFHVVDU\EHIRUHLQWHUSUHWLQJWKHP7KH$3,FDOO
isc_vax_integer()FDQEHXVHGWRSHUIRUPWKHFRQYHUVLRQ

API GUIDE 323

 APPENDIX B DATA STRUCTURES

Blob buffer items

7KHIROORZLQJWDEOHOLVWVLWHPVDERXWZKLFKLQIRUPDWLRQFDQEHUHTXHVWHGDQGUHWXUQHGDQG
WKHYDOXHVUHSRUWHG

Request and return item Return value

isc_info_blob_num_segments Total number of segments
isc_info_blob_max_segment Length of the longest segment
isc_info_blob_total_length Total size, in bytes, of Blob
isc_info_blob_type Type of Blob (0: segmented, or 1: stream)
TABLE B.4 Blob information items and return values

,QDGGLWLRQWRWKHLQIRUPDWLRQ,QWHU%DVHUHWXUQVLQUHVSRQVHWRDUHTXHVW,QWHU%DVHFDQDOVR
UHWXUQRQHRUPRUHRIWKHIROORZLQJVWDWXVPHVVDJHVWRWKHUHVXOWEXIIHU(DFKVWDWXVPHVVDJH
LVRQHXQVLJQHGE\WHLQOHQJWK

Item Description
isc_info_end End of the messages
isc_info_truncated Result buffer is too small to hold any more requested information
isc_info_error Requested information is unavailable. Check the status vector for an error
code and message
TABLE B.5 Status message return items

Blob parameter buffer

$%ORE3DUDPHWHU%XIIHU %3% LVDQDSSOLFDWLRQGHILQHGE\WHYHFWRUSDVVHGDVDQDUJXPHQWWR
isc_open_blob2() or isc_create_blob2()WKDWVSHFLILHV%OREDWWULEXWHVUHTXLUHGIRU
ILOWHULQJ%OREGDWD
$%3%FRQVLVWVRIWKHIROORZLQJSDUWV
 $E\WHVSHFLI\LQJWKHYHUVLRQRIWKHSDUDPHWHUEXIIHUDOZD\VWKHFRPSLOHWLPH
FRQVWDQWLVFBESEBYHUVLRQ
 $FRQWLJXRXVVHULHVRIRQHRUPRUHFOXVWHUVRIE\WHVHDFKGHVFULELQJDVLQJOH
SDUDPHWHU

324 INTERBASE 5
DATABASE INFORMATION REQUEST BUFFER AND RESULT BUFFER

(DFKFOXVWHUFRQVLVWVRIWKHIROORZLQJSDUWV
 $RQHE\WHSDUDPHWHUW\SH7KHUHDUHFRPSLOHWLPHFRQVWDQWVGHILQHGIRUDOOWKH
SDUDPHWHUW\SHV IRUH[DPSOHLVFBESEBWDUJHWBW\SH 
 $RQHE\WHQXPEHUVSHFLI\LQJWKHQXPEHURIE\WHVWKDWIROORZLQWKHUHPDLQGHU
RIWKHFOXVWHU
 $YDULDEOHQXPEHURIE\WHVZKRVHLQWHUSUHWDWLRQGHSHQGVRQWKHSDUDPHWHU
W\SH
$OOQXPEHUVLQWKH%ORESDUDPHWHUEXIIHUPXVWEHUHSUHVHQWHGLQDJHQHULFIRUPDWZLWKWKH
OHDVWVLJQLILFDQWE\WHILUVWDQGWKHPRVWVLJQLILFDQWE\WHODVW6LJQHGQXPEHUVVKRXOGKDYHWKH
VLJQLQWKHODVWE\WH7KH$3,IXQFWLRQisc_vax_integer()FDQEHXVHGWRUHYHUVHWKHE\WH
RUGHURIDQXPEHU)RUPRUHLQIRUPDWLRQDERXWisc_vax_integer()VHH´LVFBYD[BLQWHJHU µ
RQSDJH RI&KDSWHU´$3,)XQFWLRQ5HIHUHQFHµ
7KHIROORZLQJWDEOHOLVWVWKHSDUDPHWHUW\SHVDQGWKHLUPHDQLQJ)RUOLVWVRIWKHSRVVLEOH
VXEW\SHVDQGFKDUDFWHUVHWVVHH´%OREGHVFULSWRUµRQSDJH 

Parameter type Description

isc_bpb_target_type Target subtype
isc_bpb_source_type Source subtype
isc_bpb_target_interp Target character set
isc_bpb_source_interp Source character set
TABLE B.6 Blob parameter buffer parameter types

Database information request buffer and result buffer

7KHisc_database_info()FDOOHQDEOHVDQDSSOLFDWLRQWRTXHU\IRULQIRUPDWLRQDERXWDQ
DWWDFKHGGDWDEDVH
isc_database_info()UHTXLUHVWZRDSSOLFDWLRQSURYLGHGEXIIHUVDUHTXHVWEXIIHUZKHUHWKH
DSSOLFDWLRQVSHFLILHVWKHLQIRUPDWLRQLWQHHGVDQGDUHVXOWEXIIHUZKHUH,QWHU%DVHUHWXUQVWKH
UHTXHVWHGLQIRUPDWLRQ$QDSSOLFDWLRQSRSXODWHVWKHUHTXHVWEXIIHUZLWKLQIRUPDWLRQSULRU
WRFDOOLQJisc_database_info().,QWHU%DVHUHWXUQVLQIRUPDWLRQLQWKHUHVXOWEXIIHU,I
,QWHU%DVHDWWHPSWVWRSDVVEDFNPRUHLQIRUPDWLRQWKDQFDQILWLQWKHUHVXOWEXIIHULWSXWVWKH
YDOXHLVFBLQIRBWUXQFDWHGGHILQHGLQLEDVHKLQWKHILQDOE\WHRIWKHUHVXOWEXIIHU

API GUIDE 325

 APPENDIX B DATA STRUCTURES

Request buffer
7KHUHTXHVWEXIIHULVDE\WHYHFWRULQWRZKLFKLVSODFHGDVHTXHQFHRIE\WHYDOXHVRQHSHU
UHTXHVWHGLWHPRILQIRUPDWLRQ(DFKE\WHLVDQLWHPW\SHVSHFLI\LQJWKHNLQGRILQIRUPDWLRQ
GHVLUHG&RPSLOHWLPHFRQVWDQWVIRUDOOLWHPW\SHVDUHGHILQHGLQLEDVHKDQGVKRZQEHORZ

Result buffer
7KHUHVXOWEXIIHULVDE\WHYHFWRULQZKLFK,QWHU%DVHUHWXUQVDVHULHVRIFOXVWHUVRILQIRUPDWLRQ
RQHSHULWHPUHTXHVWHG(DFKFOXVWHUFRQVLVWVRIWKUHHSDUWV
 $RQHE\WHLWHPUHWXUQW\SH7KHVHDUHWKHVDPHDVWKHLWHPW\SHVVSHFLILHGLQWKH
UHTXHVWEXIIHU
 $WZRE\WHQXPEHUVSHFLI\LQJWKHQXPEHURIE\WHVWKDWIROORZLQWKHUHPDLQGHU
RIWKHFOXVWHU
 $YDOXHVWRUHGLQDYDULDEOHQXPEHURIE\WHVZKRVHLQWHUSUHWDWLRQ HJDVD
QXPEHURUDVDVWULQJRIFKDUDFWHUV GHSHQGVRQWKHLWHPUHWXUQW\SH
$FDOOLQJSURJUDPLVUHVSRQVLEOHIRULQWHUSUHWLQJWKHFRQWHQWVRIWKHUHVXOWEXIIHUDQGIRU
GHFLSKHULQJHDFKFOXVWHUDVDSSURSULDWH,QPDQ\FDVHVWKHYDOXHVLPSO\FRQWDLQVDQXPEHU
RUDVWULQJ VHTXHQFHRIFKDUDFWHUV %XWLQRWKHUFDVHVWKHYDOXHLVDQXPEHURIE\WHVZKRVH
LQWHUSUHWDWLRQGHSHQGVRQWKHLWHPUHWXUQW\SH
7KHFOXVWHUVUHWXUQHGWRWKHUHVXOWEXIIHUDUHQRWDOLJQHG)XUWKHUPRUHDOOQXPEHUVDUH
UHSUHVHQWHGLQDJHQHULFIRUPDWZLWKWKHOHDVWVLJQLILFDQWE\WHILUVWDQGWKHPRVWVLJQLILFDQW
E\WHODVW6LJQHGQXPEHUVKDYHWKHVLJQLQWKHODVWE\WH&RQYHUWWKHQXPEHUVWRDGDWDW\SH
QDWLYHWR\RXUV\VWHPLIQHFHVVDU\EHIRUHLQWHUSUHWLQJWKHP7KH$3,FDOO
isc_vax_integer()FDQEHXVHGWRSHUIRUPWKHFRQYHUVLRQ
,QDGGLWLRQWRWKHLQIRUPDWLRQ,QWHU%DVHUHWXUQVLQUHVSRQVHWRDUHTXHVW,QWHU%DVHFDQDOVR
UHWXUQRQHRUPRUHRIWKHIROORZLQJVWDWXVPHVVDJHVWRWKHUHVXOWEXIIHU(DFKVWDWXVPHVVDJH
LVRQHXQVLJQHGE\WHLQOHQJWK

Item Description
isc_info_end End of the messages
isc_info_truncated Result buffer is too small to hold any more requested information
isc_info_error Requested information is unavailable; check the status vector for an error code
and message
TABLE B.7 Status message return items

326 INTERBASE 5
DATABASE INFORMATION REQUEST BUFFER AND RESULT BUFFER

Request buffer items and result buffer values

7KHIROORZLQJVHFWLRQVVKRZWKHUHTXHVWEXIIHULWHPVDQGUHVXOWEXIIHUFRQWHQWVIRUWKH
IROORZLQJFDWHJRULHVRIGDWDEDVHLQIRUPDWLRQ
g 'DWDEDVHFKDUDFWHULVWLFV
g (QYLURQPHQWDOFKDUDFWHULVWLFV
g 3HUIRUPDQFHVWDWLVWLFV
g 'DWDEDVHRSHUDWLRQFRXQWV

API GUIDE 327

 APPENDIX B DATA STRUCTURES

4 'DWDEDVHFKDUDFWHULVWLFV
6HYHUDOLWHPVDUHSURYLGHGIRUGHWHUPLQLQJGDWDEDVHFKDUDFWHULVWLFVVXFKDVLWVVL]HDQGPDMRU
DQGPLQRU2'6YHUVLRQQXPEHUV7KHIROORZLQJWDEOHOLVWVWKHUHTXHVWEXIIHULWHPVWKDWFDQ
EHSDVVHGDQGWKHLQIRUPDWLRQUHWXUQHGLQWKHUHVXOWEXIIHUIRUHDFKLWHPW\SH

Request buffer item Result buffer contents

isc_info_allocation Number of database pages allocated
isc_info_base_level Database version (level) number:
1 byte containing the number 1
1 byte containing the version number
isc_info_db_id Database file name and site name:
• 1 byte containing the number 2
• 1 byte containing the length, d, of the database file name in bytes
• A string of d bytes, containing the database file name
• 1 byte containing the length, l, of the site name in bytes
• A string of l bytes, containing the site name
isc_info_implementation Database implementation number:
• 1 byte containing a 1
• 1 byte containing the implementation number
• 1 byte containing a “class” number, either 1 or 12
TABLE B.8 Database information items for database characteristics

328 INTERBASE 5
DATABASE INFORMATION REQUEST BUFFER AND RESULT BUFFER

Request buffer item Result buffer contents

isc_info_no_reserve 0 or 1
• 0 indicates space is reserved on each database page for holding
backup versions of modified records [Default]
• 1 indicates no space is reserved for such records
isc_info_ods_minor_version On-disk structure (ODS) minor version number; an increase in a minor
version number indicates a non-structural change, one that still allows
the database to be accessed by database engines with the same major
version number but possibly different minor version numbers
isc_info_ods_version ODS major version number
• Databases with different major version numbers have different
physical layouts; a database engine can only access databases with a
particular ODS major version number
• Trying to attach to a database with a different ODS number results in
an error
isc_info_page_size Number of bytes per page of the attached database; use with
isc_info_allocation to determine the size of the database
isc_info_version Version identification string of the database implementation:
• 1 byte containing the number 1
• 1 byte specifying the length, n, of the following string
• n bytes containing the version identification string
TABLE B.8 Database information items for database characteristics (continued)

API GUIDE 329

 APPENDIX B DATA STRUCTURES

4 (QYLURQPHQWDOFKDUDFWHULVWLFV
6HYHUDOLWHPVDUHSURYLGHGIRUGHWHUPLQLQJHQYLURQPHQWDOFKDUDFWHULVWLFVVXFKDVWKHDPRXQW
RIPHPRU\FXUUHQWO\LQXVHRUWKHQXPEHURIGDWDEDVHFDFKHEXIIHUVFXUUHQWO\DOORFDWHG
7KHVHLWHPVDUHGHVFULEHGLQWKHIROORZLQJWDEOH

Request buffer item Result buffer contents

isc_info_current_memory Amount of server memory (in bytes) currently in use
isc_info_forced_writes Number specifying the mode in which database writes are performed (0
for asynchronous, 1 for synchronous)
isc_info_max_memory Maximum amount of memory (in bytes) used at one time since the first
process attached to the database
isc_info_num_buffers Number of memory buffers currently allocated
isc_info_sweep_interval Number of transactions that are committed between “sweeps” to remove
database record versions that are no longer needed
isc_info_user_names NetWare only. Names of all the users currently attached to the database;
for each such user, the result buffer will contain an isc_info_user_names
byte followed by a 1-byte length specifying the number of bytes in the
user name, followed by the user name
TABLE B.9 Database information items for environmental characteristics

1RWDOOHQYLURQPHQWDOLQIRUPDWLRQLWHPVDUHDYDLODEOHRQDOOSODWIRUPV

4 3HUIRUPDQFHVWDWLVWLFV
7KHUHDUHIRXULWHPVSURYLGLQJSHUIRUPDQFHVWDWLVWLFVIRUDGDWDEDVH7KHVHVWDWLVWLFV
DFFXPXODWHIRUDGDWDEDVHIURPWKHPRPHQWLWLVILUVWDWWDFKHGE\DQ\SURFHVVXQWLOWKHODVW
UHPDLQLQJSURFHVVGHWDFKHVIURPWKHGDWDEDVH$SURJUDPUHTXHVWLQJWKLVLQIRUPDWLRQ
WKHUHIRUHVHHVLQIRUPDWLRQSHUWDLQLQJWRLWVRZQDWWDFKPHQWDQGDOORWKHUDWWDFKPHQWV
)RUH[DPSOHWKHYDOXHUHWXUQHGIRULVFBLQIRBUHDGVLVWKHQXPEHURIUHDGVVLQFHWKHFXUUHQW
GDWDEDVHZDVILUVWDWWDFKHGLWLVDQDJJUHJDWHRIDOOUHDGVGRQHE\DOODWWDFKHGSURFHVVHVUDWKHU
WKDQWKHQXPEHURIUHDGVGRQHIRUWKHFDOOLQJSURJUDPVLQFHLWDWWDFKHGWRWKHGDWDEDVH

330 INTERBASE 5
DATABASE INFORMATION REQUEST BUFFER AND RESULT BUFFER

7KHLWHPVSURYLGLQJSHUIRUPDQFHVWDWLVWLFVDUHVXPPDUL]HGLQWKHIROORZLQJWDEOH

Request buffer item Result buffer contents

isc_info_fetches Number of reads from the memory buffer cache
isc_info_marks Number of writes to the memory buffer cache
isc_info_reads Number of page reads
isc_info_writes Number of page writes
TABLE B.10 Database information items for performance statistics

4 'DWDEDVHRSHUDWLRQFRXQWV
6HYHUDOLQIRUPDWLRQLWHPVDUHSURYLGHGIRUGHWHUPLQLQJWKHQXPEHURIYDULRXVGDWDEDVH
RSHUDWLRQVSHUIRUPHGE\WKHFXUUHQWO\DWWDFKHGFDOOLQJSURJUDP7KHVHYDOXHVDUHFDOFXODWHG
RQDSHUWDEOHEDVLV
:KHQDQ\RIWKHVHLQIRUPDWLRQLWHPVLVUHTXHVWHG,QWHU%DVHUHWXUQVWRWKHUHVXOWEXIIHU
 E\WHVSHFLI\LQJWKHLWHPW\SH IRUH[DPSOHLVFBLQIRBLQVHUWBFRXQW 
 E\WHVWHOOLQJKRZPDQ\E\WHVFRPSRVHWKHVXEVHTXHQWYDOXHSDLUV
 $SDLURIYDOXHVIRUHDFKWDEOHLQWKHGDWDEDVHRQZKLFKWKHUHTXHVWHGW\SHRI
RSHUDWLRQKDVRFFXUUHGVLQFHWKHGDWDEDVHZDVODVWDWWDFKHG
(DFKSDLUFRQVLVWVRI
 E\WHVVSHFLI\LQJWKHWDEOH,'
 E\WHVOLVWLQJWKHQXPEHURIRSHUDWLRQV IRUH[DPSOHLQVHUWV GRQHRQWKDWWDEOH
7RGHWHUPLQHDQDFWXDOWDEOHQDPHIURPDWDEOH,'TXHU\WKH5'%5(/$7,21V\VWHPWDEOH

API GUIDE 331

 APPENDIX B DATA STRUCTURES

7KHIROORZLQJWDEOHGHVFULEHVWKHLWHPVZKLFKUHWXUQFRXQWYDOXHVIRURSHUDWLRQVRQWKH
GDWDEDVH

Request buffer item Result buffer contents

isc_info_backout_count Number of removals of a version of a record
isc_info_delete_count Number of database deletes since the database was last attached
isc_info_expunge_count Number of removals of a record and all of its ancestors, for records
whose deletions have been committed
isc_info_insert_count Number of inserts into the database since the database was last
attached
isc_info_purge_count Number of removals of old versions of fully mature records (records
committed, resulting in older—ancestor—versions no longer being
needed)
isc_info_read_idx_count Number of reads done via an index since the database was last
attached
isc_info_read_seq_count Number of sequential database reads, i.e., the number of sequential
table scans (row reads) done on each table since the database was
last attached
isc_info_update_count Number of database updates since the database was last attached
TABLE B.11 Database information items for operation counts

$'DWDEDVH3DUDPHWHU%XIIHU '3% LVDQDSSOLFDWLRQGHILQHGE\WHYHFWRUSDVVHGDVDQDUJXPHQW

WRisc_attach_database()WKDWVSHFLILHVGHVLUHGGDWDEDVHFKDUDFWHULVWLFV
$'3%FRQVLVWVRIWKHIROORZLQJSDUWV
 $E\WHVSHFLI\LQJWKHYHUVLRQRIWKHSDUDPHWHUEXIIHUDOZD\VWKHFRPSLOHWLPH
FRQVWDQWLVFBGSEBYHUVLRQ
 $FRQWLJXRXVVHULHVRIRQHRUPRUHFOXVWHUVRIE\WHVHDFKGHVFULELQJDVLQJOH
SDUDPHWHU
(DFKFOXVWHUFRQVLVWVRIWKHIROORZLQJSDUWV
 $RQHE\WHSDUDPHWHUW\SH7KHUHDUHFRPSLOHWLPHFRQVWDQWVGHILQHGIRUDOOWKH
SDUDPHWHUW\SHV IRUH[DPSOHLVFBGSEBQXPBEXIIHUV 
 $RQHE\WHQXPEHUVSHFLI\LQJWKHQXPEHURIE\WHVWKDWIROORZLQWKHUHPDLQGHU
RIWKHFOXVWHU

332 INTERBASE 5
DATABASE INFORMATION REQUEST BUFFER AND RESULT BUFFER

 $YDULDEOHQXPEHURIE\WHVZKRVHLQWHUSUHWDWLRQ DVDQXPEHURUDVDVWULQJRI
FKDUDFWHUVIRUH[DPSOH GHSHQGVRQWKHSDUDPHWHUW\SH
7KHIROORZLQJWDEOHOLVWV'3%LWHPVE\SXUSRVH

User Validation Item

User name isc_dpb_user_name
Password isc_dpb_password
Encrypted password isc_dpb_password_enc
System database administrator’s user name isc_dpb_sys_user_name
Authorization key for a software license isc_dpb_license
Database encryption key isc_dpb_encrypt_key
Environmental control
Number of cache buffers isc_dpb_num_buffers
dbkey context scope isc_dpb_dbkey_scope
System management
Force writes to the database to be done asynchronously or isc_dpb_force_write
synchronously
Specify whether or not to reserve a small amount of space on each isc_dpb_no_reserve
database page for holding backup versions of records when
modifications are made.
Specify whether or not the database should be marked as damaged isc_dpb_damaged
Perform consistency checking of internal structures isc_dpb_verify
Shadow control
Activate the database shadow, an optional, duplicate, in-sync copy isc_dpb_activate_shadow
of the database
Delete the database shadow isc_dpb_delete_shadow
TABLE B.12 DPB parameters

API GUIDE 333

 APPENDIX B DATA STRUCTURES

User Validation Item

Replay logging system control
Activate a replay logging system to keep track of all database calls isc_dpb_begin_log
Deactivate the replay logging system isc_dpb_quit_log
Character set and message file specification
Language-specific message file isc_dpb_lc_messages
Character set to be utilized isc_dpb_lc_ctype
TABLE B.12 DPB parameters (continued)

7KHIROORZLQJWDEOHOLVWV'3%SDUDPHWHUVLQDOSKDEHWLFDORUGHU)RUHDFKSDUDPHWHULWOLVWVLWV
SXUSRVHWKHOHQJWKLQE\WHVRIDQ\YDOXHVSDVVHGZLWKWKHSDUDPHWHUDQGWKHYDOXHWRSDVV

Parameter Purpose Length Value

isc_dpb_activate_shadow Directive to activate the database shadow, 1 (Ignored) 0 (Ignored)
which is an optional, duplicate, in-sync copy of
the database
isc_dpb_damaged Number signifying whether or not the 1 0 or 1
database should be marked as damaged;
1 = mark as damaged, 0 = do not mark as
damaged
isc_dpb_dbkey_scope Scope of dbkey context; 0 limits scope to the 1 0 or 1
current transaction, 1 extends scope to the
database session.
isc_dpb_delete_shadow Directive to delete a database shadow that is 1 (Ignored) 0 (Ignored)
no longer needed
isc_dpb_encrypt_key String encryption key, up to 255 characters Number of bytes in String containing
string key
isc_dpb_force_write Specifies whether database writes are 1 0 or 1
synchronous or asynchronous;
0 = asynchronous, 1 = synchronous
isc_dpb_lc_ctype String specifying the character set to be Number of bytes in String containing
utilized string character set name
TABLE B.13 Alphabetical list of DPB parameters

334 INTERBASE 5
DATABASE INFORMATION REQUEST BUFFER AND RESULT BUFFER

Parameter Purpose Length Value

isc_dpb_lc_messages String specifying a language-specific message Number of bytes in String containing
file string message file name
isc_dpb_license String authorization key for a software license Number of bytes in String containing
string key
isc_dpb_no_reserve Specifies whether or not a small amount of 1 0 or 1
space on each database page is reserved for
holding backup versions of records when
modifications are made; keep backup versions
on the same page as the primary record to
optimize update activity
0 (default) = reserve space
1= do not reserve space
isc_dpb_num_buffers Number of database cache buffers to allocate 1 Number of
for use with the database buffers to allocate
Default = 75
isc_dpb_password String password, up to 255 characters Number of bytes in String containing
string password
isc_dpb_password_enc String encrypted password, up to 255 Number of bytes in String containing
characters string password
isc_dpb_sys_user_name String system DBA name, up to 255 characters Number of bytes in String containing
string SYSDBA name
isc_dpb_user_name String user name, up to 255 characters Number of bytes in String containing
string user name
TABLE B.13 Alphabetical list of DPB parameters (continued)

6RPHSDUDPHWHUVVXFKDVLVFBGSEBGHOHWHBVKDGRZDUHGLUHFWLYHVWKDWGRQRWUHTXLUHDGGLWLRQDO
SDUDPHWHUV(YHQVR\RXPXVWVWLOOSURYLGHOHQJWKDQGYDOXHE\WHVIRUWKHVHSDUDPHWHUV6HW
OHQJWKWRDQGYDOXHWR,QWHU%DVHLJQRUHVWKHVHSDUDPHWHUYDOXHVEXWWKH\DUHUHTXLUHGWR
PDLQWDLQWKHIRUPDWRIWKH'3%

API GUIDE 335

 APPENDIX B DATA STRUCTURES

SQL datatype macro constants

,QWHU%DVHGHILQHVDVHWRIPDFURFRQVWDQWVWRUHSUHVHQW64/GDWDW\SHVDQG18//VWDWXV
LQIRUPDWLRQLQDQ;64/9$5$QDSSOLFDWLRQVKRXOGXVHWKHVHPDFURFRQVWDQWVWRVSHFLI\WKH
GDWDW\SHRISDUDPHWHUVDQGWRGHWHUPLQHWKHGDWDW\SHVRIVHOHFWOLVWLWHPVLQDQ64/
VWDWHPHQW7KHIROORZLQJWDEOHOLVWVHDFK64/GDWDW\SHLWVFRUUHVSRQGLQJPDFURFRQVWDQW
H[SUHVVLRQ&GDWDW\SHRU,QWHU%DVHW\SHGHIDQGZKHWKHURUQRWWKHVTOLQGILHOGLVXVHGWR
LQGLFDWHDSDUDPHWHURUYDULDEOHWKDWFRQWDLQV18//RUXQNQRZQGDWD

sqlind
SQL datatype Macro expression C datatype or typedef used?
Array SQL_ARRAY ISC_QUAD No
Array SQL_ARRAY + 1 ISC_QUAD Yes
Blob SQL_BLOB ISC_QUAD No
Blob SQL_BLOB + 1 ISC_QUAD Yes
CHAR SQL_TEXT char[ ] No
CHAR SQL_TEXT + 1 char[ ] Yes
DATE SQL_DATE ISC_QUAD No
DATE SQL_DATE + 1 ISC_QUAD Yes
DECIMAL SQL_SHORT, SQL_LONG, int, long, or double No
or SQL_DOUBLE

DECIMAL SQL_SHORT + 1, SQL_LONG + 1, int, long, or double Yes

or SQL_DOUBLE + 1

DOUBLE PRECISON SQL_DOUBLE double No

DOUBLE PRECISION SQL_DOUBLE + 1 double Yes
INTEGER SQL_LONG long No
INTEGER SQL_LONG + 1 long Yes
FLOAT SQL_FLOAT float No
FLOAT SQL_FLOAT + 1 float Yes
TABLE B.14 SQL datatypes, macro expressions, and C datatypes

336 INTERBASE 5
SQL DATATYPE MACRO CONSTANTS

sqlind
SQL datatype Macro expression C datatype or typedef used?
NUMERIC SQL_SHORT, SQL_LONG, int, long, or double No
or SQL_DOUBLE

NUMERIC SQL_SHORT + 1, SQL_LONG + 1, int, long, or double Yes

or SQL_DOUBLE + 1

SMALLINT SQL_SHORT short No

SMALLINT SQL_SHORT + 1 short Yes
VARCHAR SQL_VARYING First 2 bytes: short containing No
the length of the character string.
Remaining bytes: char[ ]
VARCHAR SQL_VARYING + 1 First 2 bytes: short containing Yes
the length of the character string.
Remaining bytes: char[ ]
TABLE B.14 SQL datatypes, macro expressions, and C datatypes (continued)

'(&,0$/DQG180(5,&GDWDW\SHVDUHVWRUHGLQWHUQDOO\DV60$//,17,17(*(5RU
'28%/(35(&,6,21GDWDW\SHV7RVSHFLI\WKHFRUUHFWPDFURH[SUHVVLRQWRSURYLGHIRUD
'(&,0$/RU180(5,&FROXPQXVHisqlWRH[DPLQHWKHFROXPQGHILQLWLRQLQWKHWDEOHWRVHH
KRZ,QWHU%DVHLVVWRULQJFROXPQGDWDWKHQFKRRVHDFRUUHVSRQGLQJPDFURH[SUHVVLRQ
7KHGDWDW\SHLQIRUPDWLRQIRUDSDUDPHWHURUVHOHFWOLVWLWHPLVFRQWDLQHGLQWKHVTOW\SHILHOGRI
WKH;64/9$5VWUXFWXUH7KHYDOXHFRQWDLQHGLQVTOW\SHSURYLGHVWZRSLHFHVRILQIRUPDWLRQ
g 7KHGDWDW\SHRIWKHSDUDPHWHURUVHOHFWOLVWLWHP
g :KHWKHUVTOLQGLVXVHGWRLQGLFDWH18//YDOXHV,IVTOLQGLVXVHGLWVYDOXHVSHFLILHVZKHWKHUWKH
SDUDPHWHURUVHOHFWOLVWLWHPLV18//  RUQRW18//  
)RUH[DPSOHLIVTOW\SHHTXDOV64/B7(;7WKHSDUDPHWHURUVHOHFWOLVWLWHPLVD&+$5WKDWGRHV
QRWXVHVTOLQGWRFKHFNIRUD18//YDOXH EHFDXVHLQWKHRU\18//YDOXHVDUHQRWDOORZHGIRU
LW ,IVTOW\SHHTXDOV64/B7(;7WKHQVTOLQGFDQEHFKHFNHGWRVHHLIWKHSDUDPHWHURU
VHOHFWOLVWLWHPLV18//
7KH&ODQJXDJHH[SUHVVLRQVTOW\SH SURYLGHVDXVHIXOWHVWRIZKHWKHUDSDUDPHWHURU
VHOHFWOLVWLWHPFDQFRQWDLQD18//7KHH[SUHVVLRQHYDOXDWHVWRLIWKHSDUDPHWHURU
VHOHFWOLVWLWHPFDQQRWFRQWDLQD18//DQGLIWKHSDUDPHWHURUVHOHFWOLVWLWHPFDQFRQWDLQ
D18//

API GUIDE 337

 APPENDIX B DATA STRUCTURES

Status vector
0RVW$3,IXQFWLRQVUHWXUQVWDWXVLQIRUPDWLRQWKDWLQGLFDWHVVXFFHVVRUIDLOXUH6WDWXV
LQIRUPDWLRQLVUHSRUWHGLQDQHUURUVWDWXVYHFWRUGHFODUHGLQDSSOLFDWLRQVDVDQDUUD\RIWZHQW\
ORQJLQWHJHUVXVLQJWKHIROORZLQJV\QWD[
#include "ibase.h"
. . .
ISC_STATUS status_vector[20];

,I\RXSODQWRZULWH\RXURZQURXWLQHVLQVWHDGRIWKH,QWHU%DVHHUURUKDQGOLQJURXWLQHVWR
UHDGDQGUHDFWWRWKHFRQWHQWVRIWKHVWDWXVYHFWRU\RXQHHGWRNQRZKRZWRLQWHUSUHWLW
,QWHU%DVHVWRUHVHUURULQIRUPDWLRQLQWKHVWDWXVYHFWRULQFOXVWHUVRIWZRRUWKUHHORQJV7KH
ILUVWFOXVWHULQWKHVWDWXVYHFWRUDOZD\VLQGLFDWHVWKHSULPDU\FDXVHRIWKHHUURU6XEVHTXHQW
FOXVWHUVPD\FRQWDLQVXSSRUWLQJLQIRUPDWLRQDERXWWKHHUURUIRUH[DPSOHVWULQJVRUQXPEHUV
IRUGLVSOD\LQDQDVVRFLDWHGHUURUPHVVDJH7KHDFWXDOQXPEHURIFOXVWHUVXVHGWRUHSRUW
VXSSRUWLQJLQIRUPDWLRQYDULHVIURPHUURUWRHUURU
,QPDQ\FDVHVDGGLWLRQDOHUURUVPD\EHUHSRUWHGLQWKHVWDWXVYHFWRU$GGLWLRQDOHUURUVDUH
UHSRUWHGLPPHGLDWHO\IROORZLQJWKHILUVWHUURUDQGLWVVXSSRUWLQJLQIRUPDWLRQLIDQ\7KHILUVW
FOXVWHUIRUHDFKDGGLWLRQDOHUURUPHVVDJHLGHQWLILHVWKHHUURU6XEVHTXHQWFOXVWHUVPD\FRQWDLQ
VXSSRUWLQJLQIRUPDWLRQDERXWWKHHUURU

Meaning of the first long in a cluster

7KHILUVWORQJLQDQ\FOXVWHULVDQXPHULFGHVFULSWRU%\H[DPLQLQJWKHQXPHULFGHVFULSWRUIRUD
FOXVWHU\RXFDQDOZD\VGHWHUPLQHWKH
g 7RWDOQXPEHURIORQJVLQWKHFOXVWHU
g .LQGRILQIRUPDWLRQUHSRUWHGLQWKHUHPDLQGHURIWKHFOXVWHU
g 6WDUWLQJORFDWLRQRIWKHQH[WFOXVWHULQWKHVWDWXVYHFWRU

338 INTERBASE 5
MEANING OF THE FIRST LONG IN A CLUSTER

7KHIROORZLQJWDEOHOLVWVSRVVLEOHYDOXHVIRUWKHILUVWORQJLQDQ\FOXVWHULQWKHVWDWXVYHFWRU
1RWHWKDWWKHILUVWFOXVWHULQWKHVWDWXVYHFWRUFDQRQO\FRQWDLQYDOXHVRIRUJUHDWHUWKDQ

Longwords in
Value cluster Meaning
0 — End of error information in the status vector
1 2 Second long is an InterBase error code
2 2 Second long is the address of string used as a replaceable parameter in a generic
InterBase error message
3 3 Second long is the length, in bytes, of a variable length string provided by the
operating system (most often this string is a file name); third long is the address of
the string
4 2 Second long is a number used as a replaceable parameter in a generic InterBase
error message
5 2 Second long is the address of an error message string requiring no further
processing before display
6 2 Second long is a VAX/VMS error code
7 2 Second long is a Unix error code
8 2 Second long is an Apollo Domain error code
9 2 Second long is an MS-DOS or OS/2 error code
10 2 Second long is an HP MPE/XL error code
11 2 Second long is an HP MPE/XL IPC error code
12 2 Second long is a NeXT/Mach error code
NOTE As InterBase is adapted to run on other hardware and software platforms, additional numeric
descriptors for specific platform and operating system error codes may be added to the end of this list.
TABLE B.15 Interpretation of status vector clusters

API GUIDE 339

 APPENDIX B DATA STRUCTURES

7KHIROORZLQJWDEOHOLVWVWKHLEDVHKGHILQHHTXLYDOHQWVRIHDFKQXPHULFGHVFULSWRU

Value #define Value #define

0 isc_arg_end 8 isc_arg_domain
1 isc_arg_gds 9 isc_arg_dos
2 isc_arg_string 10 isc_arg_mpexl
3 isc_arg_cstring 11 isc_arg_mpexl_ipc
4 isc_arg_number 15 isc_arg_next_mach
5 isc_arg_interpreted 16 isc_arg_netware
6 isc_arg_vms 17 isc_arg_win32
7 isc_arg_unix
TABLE B.16 #defines for status vector numeric descriptors

Transaction parameter buffer

7KHWUDQVDFWLRQSDUDPHWHUEXIIHU 73% LVDQRSWLRQDODSSOLFDWLRQGHILQHGE\WHYHFWRUSDVVHGDV
DQDUJXPHQWWRisc_start_transaction()WKDWVHWVXSDWUDQVDFWLRQ·VDWWULEXWHVLWVRSHUDWLQJ
FKDUDFWHULVWLFVVXFKDVZKHWKHUWKHWUDQVDFWLRQKDVUHDGDQGZULWHDFFHVVWRWDEOHVRU
UHDGRQO\DFFHVVDQGZKHWKHURUQRWRWKHUVLPXOWDQHRXVO\DFWLYHWUDQVDFWLRQVFDQVKDUHWDEOH
DFFHVVZLWKWKHWUDQVDFWLRQ(DFKWUDQVDFWLRQPD\KDYHLWVRZQ73%RUWUDQVDFWLRQVWKDW
VKDUHRSHUDWLQJFKDUDFWHULVWLFVFDQXVHWKHVDPH73%
,ID73%LVQRWFUHDWHGIRUDWUDQVDFWLRQD18//SRLQWHUPXVWEHSDVVHGWR
isc_start_transaction()LQLWVSODFH$GHIDXOWVHWRIDWWULEXWHVLVDXWRPDWLFDOO\DVVLJQHGWR
VXFKWUDQVDFWLRQV

340 INTERBASE 5
TRANSACTION PARAMETER BUFFER

$73%LVGHFODUHGLQD&SURJUDPDVDFKDUDUUD\RIRQHE\WHHOHPHQWV(DFKHOHPHQWLVD
SDUDPHWHUWKDWGHVFULEHVDVLQJOHWUDQVDFWLRQDWWULEXWH7KHILUVWHOHPHQWLQHYHU\73%PXVW
EHWKHLVFBWSEBYHUVLRQFRQVWDQW7KHIROORZLQJWDEOHOLVWVDYDLODEOH73%FRQVWDQWVGHVFULEHV
WKHLUSXUSRVHVDQGLQGLFDWHVZKLFKFRQVWDQWVDUHDVVLJQHGDVDGHIDXOWVHWRIDWWULEXWHVZKHQ
D18//73%SRLQWHULVSDVVHGWRisc_start_transaction()

Parameter Description
isc_tpb_version3 InterBase version 3 transaction
isc_tpb_consistency Table-locking transaction model
isc_tpb_concurrency High throughput, high concurrency transaction with acceptable consistency; use
of this parameter takes full advantage of the InterBase multi-generational
transaction model [Default]
isc_tpb_shared Concurrent, shared access of a specified table among all transactions.; use in
conjunction with isc_tpb_lock_read and isc_tpb_lock_write to establish the lock
option [Default]
isc_tpb_protected Concurrent, restricted access of a specified table; use in conjunction with
isc_tpb_lock_read and isc_tpb_lock_write to establish the lock option
isc_tpb_wait Lock resolution specifies that the transaction is to wait until locked resources are
released before retrying an operation [Default]
isc_tpb_nowait Lock resolution specifies that the transaction is not to wait for locks to be released,
but instead, a lock conflict error should be returned immediately
isc_tpb_read Access mode of read-only that allows a transaction only to select data from tables
isc_tpb_write Access mode of read-write that allows a transaction to select, insert, update, and
delete table data [Default]
isc_tpb_lock_read Read-only access of a specified table; use in conjunction with isc_tpb_shared,
isc_tpb_protected, and isc_tpb_exclusive to establish the lock option
isc_tpb_lock_write Read-write access of a specified table; use in conjunction with isc_tpb_shared,
isc_tpb_protected, and isc_tpb_exclusive to establish the lock option [Default]
TABLE B.17 TPB constants

API GUIDE 341

 APPENDIX B DATA STRUCTURES

Parameter Description
isc_tpb_read_committed High throughput, high concurrency transaction that can read changes committed
by other concurrent transactions; use of this parameter takes full advantage of the
InterBase multi-generational transaction model
isc_tpb_rec_version Enables an isc_tpb_read_committed transaction to read the most recently
committed version of a record even if other, uncommitted versions are pending.
isc_tpb_no_rec_version Enables an isc_tpb_read_committed transaction to read only the latest committed
version of a record
If an uncommitted version of a record is pending and isc_tpb_wait is also
specified, then the transaction waits for the pending record to be committed or
rolled back before proceeding; otherwise, a lock conflict error is reported at once
TABLE B.17 TPB constants (continued)

73%SDUDPHWHUVVSHFLI\WKHIROORZLQJFODVVHVRILQIRUPDWLRQ
g 7UDQVDFWLRQYHUVLRQQXPEHULVXVHGLQWHUQDOO\E\WKH,QWHU%DVHHQJLQH,WLVDOZD\VEHWKHILUVW
DWWULEXWHVSHFLILHGLQWKH73%DQGPXVWDOZD\VEHVHWWRLVFBWSEBYHUVLRQ
g $FFHVVPRGHGHVFULEHVWKHDFWLRQVWKDWFDQEHSHUIRUPHGE\WKHIXQFWLRQVDVVRFLDWHGZLWKWKH
WUDQVDFWLRQ9DOLGDFFHVVPRGHVDUH
LVFBWSEBUHDG
LVFBWSEBZULWH
g ,VRODWLRQOHYHOGHVFULEHVWKHYLHZRIWKHGDWDEDVHJLYHQDWUDQVDFWLRQDVLWUHODWHVWRDFWLRQV
SHUIRUPHGE\RWKHUVLPXOWDQHRXVO\RFFXUULQJWUDQVDFWLRQV9DOLGLVRODWLRQOHYHOVDUH
LVFBWSEBFRQFXUUHQF\
LVFBWSEBFRQVLVWHQF\
LVFBWSEBUHDGBFRPPLWWHGLVFBWSEBUHFBYHUVLRQ
LVFBWSEBUHDGBFRPPLWWHGLVFBWSEBQRBUHFBYHUVLRQ
g /RFNUHVROXWLRQGHVFULEHVKRZDWUDQVDFWLRQVKRXOGUHDFWLIDORFNFRQIOLFWRFFXUV9DOLGORFN
UHVROXWLRQVDUH
LVFBWSEBZDLW
LVFBWSEBQRZDLW
g 7DEOHUHVHUYDWLRQRSWLRQDOO\GHVFULEHVDQDFFHVVPHWKRGDQGORFNUHVROXWLRQIRUDVSHFLILHGWDEOH
WKDWWKHWUDQVDFWLRQDFFHVVHV:KHQWDEOHUHVHUYDWLRQLVXVHGWDEOHVDUHUHVHUYHGIRUWKH
VSHFLILHGDFFHVVZKHQWKHWUDQVDFWLRQLVVWDUWHGUDWKHUWKDQZKHQWKHWUDQVDFWLRQDFWXDOO\
DFFHVVHVWKHWDEOH9DOLGUHVHUYDWLRQVDUH

342 INTERBASE 5
XSQLDA AND XSQLVAR

LVFBWSEBVKDUHGLVFBWSEBORFNBZULWH
LVFBWSEBVKDUHGLVFBWSEBORFNBUHDG
LVFBWSEBSURWHFWHGLVFBWSEBORFNBZULWH
LVFBWSEBSURWHFWHGLVFBWSEBORFNBUHDG

XSQLDA and XSQLVAR

$OO'64/DSSOLFDWLRQVPXVWGHFODUHRQHRUPRUHH[WHQGHG64/GHVFULSWRUDUHDV
;64/'$V 
7KHXSQLDALVDKRVWODQJXDJHGDWDVWUXFWXUHWKDW'64/XVHVWRWUDQVSRUWGDWDWRRUIURPD
GDWDEDVHZKHQSURFHVVLQJDQ64/VWDWHPHQWVWULQJ7KHUHDUHWZRW\SHVRIXSQLDAVLQSXW
GHVFULSWRUVDQGRXWSXWGHVFULSWRUV%RWKLQSXWDQGRXWSXWGHVFULSWRUVDUHLPSOHPHQWHGXVLQJ
WKHXSQLDAVWUXFWXUH
6\QWD[ One field in the XSQLDA, sqlvar, is an XSQLVAR structure. The sqlvar is especially
important because one XSQLVAR must be defined for each input parameter or column
returned.

$SSOLFDWLRQVGRQRWGHFODUHLQVWDQFHVRIWKH;64/9$5DKHDGRIWLPHEXWPXVWLQVWHDG
G\QDPLFDOO\DOORFDWHVWRUDJHIRUWKHSURSHUQXPEHURI;64/9$5VWUXFWXUHVUHTXLUHGIRUHDFK
'64/VWDWHPHQWEHIRUHLWLVH[HFXWHGWKHQGHDOORFDWHLWDVDSSURSULDWHDIWHUVWDWHPHQW
H[HFXWLRQ

API GUIDE 343

 APPENDIX B DATA STRUCTURES

7KHIROORZLQJILJXUHLOOXVWUDWHVWKHUHODWLRQVKLSEHWZHHQWKH;64/'$DQGWKH;64/9$5

Single instance of XSQLDA[ ][ ]

short version
char sqldaid[8]
ISC_LONG sqldabc
short sqln
short sqld

Array of n instances of XSQLVAR

1st instance nth instance

short sqltype short sqltype
short sqlscale short sqlscale
short sqlsubtype short sqlsubtype
short sqllen short sqllen
char *sqldata char *sqldata
short *sqlind short *sqlind
short sqlname_length short sqlname_length
char sqlname[32] char sqlname[32]
short relname_length short relname_length
char relname[32] char relname[32]
short ownname_length short ownname_length
char ownname[32] char ownname[32]
short aliasname_length short aliasname_length
char aliasname[32] char aliasname[32]

$QLQSXW;64/'$FRQVLVWVRIDVLQJOH;64/'$VWUXFWXUHDQGRQH;64/9$5VWUXFWXUHIRU
HDFKLQSXWSDUDPHWHU$QRXWSXW;64/'$DOVRFRQVLVWVRIRQH;64/'$VWUXFWXUHDQGRQH
;64/9$5VWUXFWXUHIRUHDFKGDWDLWHPUHWXUQHGE\WKHVWDWHPHQW

344 INTERBASE 5
XSQLDA AND XSQLVAR

7KH
isc_dsql_prepare() isc_dsql_describe() DQG
isc_dsql_describe_bind() VWDWHPHQWV
FDQEHXVHGWRGHWHUPLQHWKHSURSHUQXPEHURI;64/9$5VWUXFWXUHVWRDOORFDWHDQGWKH
;64/'$B/(1*7+PDFURFDQEHXVHGWRDOORFDWHWKHSURSHUDPRXQWRIVSDFH

XSQLDA field descriptions

7KHIROORZLQJWDEOHGHVFULEHVWKHILHOGVWKDWFRPSULVHWKH;64/'$VWUXFWXUH

Field definition Description

short version Indicates the version of the XSQLDA structure; set by an application
The current version is defined in ibase.h as SQLDA_VERSION1
char sqldaid[8] Reserved for future use
ISC_LONG sqldabc Reserved for future use
short sqln Indicates the number of elements in the sqlvar array; the application should set this field
whenever it allocates storage for a descriptor
short sqld Indicates the number of parameters for an input XSQLDA, or the number of select-list
items for an output XSQLDA; set by InterBase during an isc_dsql_prepare,
isc_dsql_describe(), or isc_dsql_describe_bind()
For an input descriptor, an sqld of 0 indicates that the SQL statement has no parameters;
for an output descriptor, an sqld of 0 indicates that the SQL statement is not a SELECT
statement
XSQLVAR sqlvar The array of XSQLVAR structures; the number of elements in the array is specified in the
sqln field
TABLE B.18 XSQLDA field descriptions

API GUIDE 345

 APPENDIX B DATA STRUCTURES

XSQLVAR field descriptions

7KHIROORZLQJWDEOHGHVFULEHVWKHILHOGVWKDWFRPSULVHWKH;64/9$5VWUXFWXUH

Field definition Description

short sqltype Indicates the SQL datatype of parameters or select-list items; set by InterBase
during isc_dsql_prepare, isc_dsql_describe(), or
isc_dsql_describe_bind()
short sqlscale Provides scale, specified as a negative number, for exact numeric datatypes
(DECIMAL, NUMERIC); set by InterBase during isc_dsql_prepare,
isc_dsql_describe(), or isc_dsql_describe_bind()
short sqlsubtype Specifies the subtype for Blob data; set by InterBase during isc_dsql_prepare,
isc_dsql_describe(), or isc_dsql_describe_bind()
short sqllen Indicates the maximum size, in bytes, of data in the sqldata field; set by InterBase
during isc_dsql_prepare, isc_dsql_describe(), or
isc_dsql_describe_bind()
char *sqldata For input descriptors, specifies either the address of a select-list item or a
parameter; set by the application
For output descriptors, contains a value for a select-list item; set by InterBase
short *sqlind On input, specifies the address of an indicator variable; set by an application
On output, specifies the address of column indicator value for a select-list item
following a FETCH
A value of 0 indicates that the column is not NULL; a value of –1 indicates the
column is NULL; set by InterBase
short sqlname_length Specifies the length, in bytes, of the data in field, sqlname; set by InterBase
during isc_dsql_prepare() or isc_dsql_describe()
char sqlname[32] Contains the name of the column. Not NULL (\0) terminated; set by InterBase
during isc_dsql_prepare() or isc_dsql_describe()
short relname_length Specifies the length, in bytes, of the data in field, relname; set by InterBase during
isc_dsql_prepare() or isc_dsql_describe()
TABLE B.19 XSQLVAR field descriptions

346 INTERBASE 5
XSQLDA AND XSQLVAR

Field definition Description

char relname[32] Contains the name of the table; not NULL (\0) terminated, set by InterBase during
isc_dsql_prepare() or isc_dsql_describe()
short ownname_length Specifies the length, in bytes, of the data in field, ownname; set by InterBase
during isc_dsql_prepare() or isc_dsql_describe()
char ownname[32] Contains the name of the table owner; not NULL (\0) terminated, set by InterBase
during isc_dsql_prepare() or isc_dsql_describe()
short aliasname_length Specifies the length, in bytes, of the data in field, aliasname; set by InterBase
during isc_dsql_prepare() or isc_dsql_describe()
char aliasname[32] Contains the alias name of the column or the column name if no alias exists; not
NULL (\0) terminated, set by InterBase during isc_dsql_prepare() or
isc_dsql_describe()
TABLE B.19 XSQLVAR field descriptions (continued)

API GUIDE 347

Index

A DUJXPHQWV6HHSDUDPHWHUV
DFFHVVPRGHSDUDPHWHU  DUUD\EXIIHUV 
DFFHVVLQJ DUUD\FROXPQV 
DUUD\V ² DVVRFLDWLQJZLWKDUUD\V 
DUUD\V'64/DSSOLFDWLRQV  VHOHFWLQJ 
DFWLRQV6HHHYHQWV VL]HVHWWLQJ 
DGGUHVVHV ZULWLQJGDWDWR ²
HUURUPHVVDJHV  DUUD\GHVFULSWRUV ²
QXPHULFGDWD  FUHDWLQJ 
DJJUHJDWHIXQFWLRQV GDWDW\SHV 
DUUD\VDQG  IODJVVHWWLQJ 
$/,*1PDFUR  LQLWLDOL]LQJ 
DOORFDWLQJPHPRU\  SRSXODWLQJ ²
DQLPDWLRQ  VHWWLQJILHOGVGLUHFWO\ 
$3,FDOOVUHIHUHQFLQJGHUHIHUHQFLQJ  DUUD\HOHPHQWV 
$3,IXQFWLRQV ² VL]HVHWWLQJ 
DUUD\V  DUUD\,'V 
%/2%GDWD  GHFODULQJ 
FDWHJRULHVVXPPDUL]HG ² IHWFKLQJ 
FRQYHUVLRQV  LQLWLDOL]LQJ 
GDWDEDVH  DUUD\VOLFHV ²
'64/  FKDQJLQJRQHVOLFH 
HUURUKDQGOLQJ  FUHDWLQJGDWDEXIIHUV 
'64/DSSOLFDWLRQV ² GHILQHG 
HYHQWV  UHDGLQJRQHVOLFH 
H[DPSOHSURJUDPV  ZULWLQJGDWDWR ²
LQIRUPDWLRQDO  DUUD\V ²
SURFHVVLQJ64/VWDWHPHQWV ² 6HHDOVRHUURUVWDWXVDUUD\
;64/'$VDQG  $3,IXQFWLRQV 
SURWRW\SHV  DVVRFLDWLQJZLWKDUUD\FROXPQV 
WUDQVDFWLRQV  FROXPQPDMRURUGHUVSHFLI\LQJ 
DSSOLFDWLRQV FUHDWLQJ 
6HHDOVR'64/DSSOLFDWLRQV GURSSLQJ 
%/2%GDWDDQG  '64/DSSOLFDWLRQVDQG 
DOORFDWLQJ  PXOWLGLPHQVLRQDO 
W\SHFKHFNLQJ  GLPHQVLRQVUDQJH 
FRPSLOLQJ6HHFRPSLOLQJ QHVWHG 
HUURUKDQGOLQJ  RYHUYLHZ 
OLQNLQJ6HHOLQNLQJ SURFHVVLQJ 
PRQLWRULQJSHUIRUPDQFH  UHDGLQJGDWD ²
SURJUDPPLQJ ² FUHDWLQJGDWDEXIIHUV 
UHFRYHULQJGDWD  UHWULHYLQJGDWD 
:LQGRZV6HH:LQGRZVDSSOLFDWLRQV VHOHFWHGURZV 

API GUIDE i
 URZPDMRURUGHUVSHFLI\LQJ  WUDQVODWLQJ 
VXEVFULSWV  XSGDWLQJ ²
VXEVHWV %/2%GDWDW\SH
UHWULHYLQJ  DUUD\VDQG 
ZULWLQJWR  18//YDOXHV 
XSGDWLQJ ² XVHUGHILQHG 
DV\QFKURQRXVHYHQWV  %/2%GHVFULSWRUV ²
FDQFHOLQJQRWLILFDWLRQ  SRSXODWLQJ ²
UHTXHVWLQJQRWLILFDWLRQ  VWUXFWXUHGHILQHG 
DV\QFKURQRXVWUDSV ² %/2%ILOWHUIXQFWLRQ
FUHDWLQJ  DFWLRQPDFURGHILQLWLRQV 
DWWDFKLQJWRDGDWDEDVH  GHILQLQJ 
DWWDFKLQJWRGDWDEDVHV ² LQSXWRXWSXWILHOGV 
6HHDOVRFRQQHFWLQJWRGDWDEDVHV %/2%ILOWHUV ²
'3%VDQG  FRQWUROVWUXFWXUHGHILQHG 
RSWLRQDOHQWULHV  H[WHUQDO ²
UHOHDVLQJV\VWHPUHVRXUFHV  GHFODULQJ 
UHWULHYLQJLQIRUPDWLRQDERXW ² ZULWLQJ ²
WHPSRUDULO\  LQYRNLQJ 
:LQGRZVFOLHQWV  1HW:DUHVHUYHUVDQG 
DXWRPDWLFUHFRYHU\IXQFWLRQV  RSHQLQJ%/2%V 
VSHFLI\LQJ 
XVHUGHILQHG 
B %/2%KDQGOHV 
ELQDU\GDWD  DOORFDWLQJ 
ELQDU\ILOHW\SHVVXSSRUWHG  %/2%,'V 
ELQDU\ODUJHREMHFWV6HH%/2% FUHDWLQJ 
ELWPDSSHGLPDJHV  GHFODULQJ 
%/2% GHILQHG  UHVHWWLQJ 
%/2%$3,IXQFWLRQV  %/2%SDUDPHWHUEXIIHUV ²
%/2%FROXPQV JHQHUDWLQJ 
FUHDWLQJ ² QXPHULFIRUPDWV 
ZULWLQJGDWDWR  SDUDPHWHUW\SHV 
%/2%ILOWHUVDQG  %/2%VHJPHQWV 
%/2%GDWD ² DOORFDWLQJ 
FKDQJLQJ  GHILQHG 
FUHDWLQJ  UHDGLQJ 
GHOHWLQJ  UHWULHYLQJ 
'64/DSSOLFDWLRQVDQG ² VL]H 
IHWFKLQJ  ZULWLQJ 
ILOWHULQJ ² %/2%VXEW\SHV 
SURFHVVLQJ  ILOWHULQJ 
UHDGLQJ ² UHWULHYLQJ 
%/2%ILOWHUVDQG  VHWWLQJ 
UHWULHYLQJLQIRUPDWLRQDERXW ² %RUODQG&&6HH&ODQJXDJH
GHIDXOWV  %3%V6HH%/2%SDUDPHWHUEXIIHUV
VHOHFWLQJ ² EXIIHUV 
VWDWXVPHVVDJHVV  %/2%ILOWHUV 
VWRULQJ  FDSWXULQJHUURUPHVVDJHV 
VXSSRUW  GDWDEDVHDWWDFKPHQWV 

ii INTERBASE 5
 UHLQLWLDOL]LQJHYHQW  UHWDLQLQJFRQWH[W 
WUDQVDFWLRQV  FRPSLOLQJ 
E\WHRUGHUUHYHUVLQJ  FRQQHFWLQJWRGDWDEDVHV ²
6HHDOVRDWWDFKLQJWRGDWDEDVHV
FRQVWDQWV
C LWHPW\SHV %/2%V 
&ODQJXDJH FRQYHUWLQJ
FRQYHUWLQJGDWHV ² GDWHV ²
GLUHFWLYHV  &5($7('$7$%$6( 
HUURUKDQGOLQJ  '64/DSSOLFDWLRQV 
HYHQWQRWLILFDWLRQ  FXUVRUV
SUHGHILQHGFRQVWDQWV FORVLQJ 
LWHPW\SHV %/2%V  GHFODULQJ 
SUHGHILQHGPDFURV  '64/DSSOLFDWLRQV 
DFWLRQPHVVDJHV %/2%V  QDPLQJ 
GDWDW\SHV ;64/'$V ² RSHQLQJ 
LQIRUPDWLRQDO 64/ 
WLPHVWUXFWXUHV 
&$'ILOHV  D
FKDQJHV GDWD
XQGRLQJ  ELQDU\ 
6HHDOVRUROOEDFNV FRUUXSWHG 
FKDUDFWHUVHWV IHWFKLQJ 
%/2%GDWDDQG  '64/DSSOLFDWLRQV 
UHWULHYLQJFXUUHQW  ORVLQJ 
VHWWLQJ  SURWHFWLQJ6HHVHFXULW\
FKDUDFWHUVWULQJV UHDGLQJ ²
FRQYHUWLQJ UHFRYHULQJ 
64/VWDWHPHQWVWR  UHWULHYLQJ 
&+$5$&7(59$5<,1*GDWDW\SH VHOHFWHGURZV 
'64/DSSOLFDWLRQVDQG  VWRULQJ 
FOLHQWDSSOLFDWLRQV6HH64/FOLHQWDSSOLFDWLRQV:LQGRZV YDULDEOHOHQJWK
FOLHQWV SURFHVVLQJLQ;64/'$V 
FOLHQWOLEUDULHV  GDWDEDVH$3,IXQFWLRQV 
&/26(  GDWDEDVHKDQGOHV ²
FORVLQJ DVVLJQLQJDWUXQWLPH 
GDWDEDVHV  GHFODULQJ 
FRHUFLQJGDWDW\SHV ;64/'$V ² GHILQHG 
FROXPQQDPHV LQLWLDOL]LQJ 
VWRULQJ  PXOWLSOHGDWDEDVHV 
FROXPQPDMRURUGHU GDWDEDVHSDJHV
VSHFLI\LQJ  UHWULHYLQJLQIRUPDWLRQDERXW 
FROXPQV GDWDEDVHSDUDPHWHUEXIIHUV 
DUUD\VDQG  DOORFDWLQJVWRUDJHVSDFH 
'64/DSSOLFDWLRQV  FUHDWLQJ ²
UHWULHYLQJLQIRUPDWLRQDERXW  H[SDQGLQJ 
FRPPLWV  QXPHULFIRUPDWV 
6HHDOVRWUDQVDFWLRQV SDUDPHWHUV 
GHOD\LQJ  DGGLQJDWUXQWLPH 
H[HFXWLQJ  GDWDEDVHV

API GUIDE iii

 6HHDOVRPXOWLSOHGDWDEDVHV 6HHDOVRGHWDFKLQJIURPGDWDEDVHV
DFFHVVLQJ  GLVSOD\LQJ6HHRXWSXW
DWWDFKLQJWR  '//V 
FKDQJHVXQGRLQJ  '26DSSOLFDWLRQV 
FORVLQJ  '26HQYLURQPHQWYDULDEOHV 
FUHDWLQJ  '3%V6HHGDWDEDVHSDUDPHWHUEXIIHUV
GURSSLQJ  GURSSLQJ
SHUIRUPDQFHVWDWLVWLFV  DUUD\V 
UHIHUHQFLQJ  GDWDEDVHV 
UHWULHYLQJLQIRUPDWLRQDERXW  '64/
YHUVLRQQXPEHUV  SURJUDPPLQJPHWKRGV ²
WHPSRUDU\  '64/$3,IXQFWLRQV 
GDWDW\SHFRHUFLRQ ;64/'$V ² '64/DSSOLFDWLRQV 
GDWDW\SHPDFURFRQVWDQWV ;64/'$V ² DUUD\VDQG 
GDWDW\SHV  %/2%SURFHVVLQJ ²
DUUD\V  FORVLQJFXUVRUV 
LQGHWHUPLQDWH  GHFODULQJFXUVRUV 
'$7(GDWD  GHILQLQJFXUVRUV 
FRQYHUWLQJ ² HUURUKDQGOLQJ ²
'(&,0$/GDWDW\SH H[WHQGHGGHVFULSWRUDUHDV6HH;64/'$V
'64/DSSOLFDWLRQVDQG  IHWFKLQJGDWD 
'(&/$5(&85625  TXHULHV ²
'(&/$5(),/7(5  UHWULHYLQJLQIRUPDWLRQDERXW 
GHFODULQJ 6(/(&7VWDWHPHQWV 
DUUD\,'V  64/VWDWHPHQWV ²
%/2%GHVFULSWRUV  '64/VWDWHPHQWV
%/2%ILOWHUV  H[HFXWLQJ 
%/2%KDQGOHV  UHSHDWHGO\ 
%/2%,'V  KDQGOHV
FXUVRUV  DOORFDWLQJ 
GDWDEDVHKDQGOHV  IUHHLQJ 
HUURUVWDWXVYHFWRUV  LQSXWSDUDPHWHUV 
H[WHQGHGGHVFULSWRUDUHDV  UHWULHYLQJLQIRUPDWLRQDERXW 
WUDQVDFWLRQKDQGOHV  '64/BFORVHRSWLRQ 
GHIDXOWGLUHFWRULHV '64/BGURSRSWLRQ 
:LQGRZVFOLHQWV  G\QDPLFOLQNOLEUDULHV6HH'//V
GHIDXOWVUHWULHYLQJ G\QDPLF64/6HH'64/
%/2%V 
'(/(7(
%/2%GDWD  E
'64/DSSOLFDWLRQV  HQYLURQPHQWYDULDEOHV 
GHOHWLQJ6HHGURSSLQJ HQYLURQPHQWV
'(6&5,%(  3&V 
GHVFULSWRUDUHDV H[WHQGHG 6HH;64/'$V UHWULHYLQJLQIRUPDWLRQDERXW 
GHVFULSWRUILHOGV6HHDUUD\GHVFULSWRUV%/2%GHVFULSWRUV (3%V6HHHYHQWSDUDPHWHUEXIIHUV
GHWDFKLQJIURPGDWDEDVHV  HUURUFRGHV 
6HHDOVRGLVFRQQHFWLQJIURPGDWDEDVHV H[DPLQLQJVWDWXVYHFWRU ²
GLUHFWRULHV V\VWHP 
:LQGRZVFOLHQWV  WUDQVODWLQJ 
GLVFRQQHFWLQJIURPGDWDEDVHV  HUURUPHVVDJHV 

iv INTERBASE 5
 6HHDOVR64/HUURUPHVVDJHV ILOHW\SHV
DGGUHVVHV  %/2%GDWD 
EXLOGLQJ  ILOWHULQJ%/2%GDWD ²
GLVSOD\LQJ  6HHDOVR%/2%ILOWHUV
'64/DSSOLFDWLRQV ² IRUPDWWLQJ
HUURUVWDWXVDUUD\  HUURUPHVVDJHV 
HUURUVWDWXVYHFWRUV  IXQFWLRQSURWRW\SHV 
FKHFNLQJ 
FOXVWHUV 
GHFODULQJ  G
QXPHULFGHVFULSWRUV ² *'6'// 
QXPHULFYDOXHV 
SDUVLQJ ²
HUURUKDQGOLQJ$3,IXQFWLRQV  H
'64/DSSOLFDWLRQV ² KDQGOHV6HHGDWDEDVHKDQGOHVWUDQVDFWLRQKDQGOHV
HUURUKDQGOLQJURXWLQHV  KHDGHUILOHV6HHLEDVHK
64/  KRVWQDPHVVSHFLI\LQJ 
HUURUV 
UXQWLPH 
WUDQVDFWLRQV  I
HYHQWEXIIHUUHLQLWLDOL]LQJ  LEDVHK 
HYHQWSDUDPHWHUEXIIHUV  %/2%GHVFULSWRUV 
DOORFDWLQJ  HUURUV 
FRPSDULQJHYHQWFRXQWV  ;64/'$VWUXFWXUHV 
FUHDWLQJ  LQFOXGHILOHV6HHLEDVHK
HYHQWV  LQGHWHUPLQDWHGDWDW\SHV 
DV\QFKURQRXV  LQIRUPDWLRQLWHPPDFURV 64/ 
FDQFHOLQJQRWLILFDWLRQ  LQIRUPDWLRQDO$3,IXQFWLRQV 
UHTXHVWLQJQRWLILFDWLRQ  LQLWLDOL]LQJ
SRVWLQJ  DUUD\GHVFULSWRUV 
SURFHVVLQJ ² DUUD\,'V 
UHWULHYLQJ  %/2%KDQGOHV 
V\QFKURQRXV  %/2%,'V 
WUDQVDFWLRQFRQWURO  GDWDEDVHKDQGOHV 
ZDLWLQJRQ  WUDQVDFWLRQKDQGOHV 
H[DPSOHSURJUDPV  LQSXWGHVFULSWRUV6HH;64/'$V
(;(&87(  LQSXWILHOGV
(;(&87(,00(',$7(  %/2%ILOWHUV 
(;(&87(352&('85( LQSXWSDUDPHWHUV
'64/DSSOLFDWLRQV  '64/VWDWHPHQWV 
H[WHQGHG64/GHVFULSWRUDUHDV6HH;64/'$V ,16(57
H[WHUQDO%/2%ILOWHUV6HH%/2%ILOWHUV DUUD\V 
%/2%GDWD 
,6&B$55$<B%281'VWUXFWXUH 
F ,6&B$55$<B'(6&VWUXFWXUH 
)(7&+  LVFBDUUD\BJHWBVOLFH 
IHWFKLQJGDWD  LVFBDUUD\BORRNXSBERXQGV 
6HHDOVRUHWULHYLQJGDWD LVFBDUUD\BORRNXSBGHVF 
'64/DSSOLFDWLRQV  LVFBDUUD\BSXWBVOLFH 
),/(VWUXFWXUH  LVFBDUUD\BVHWBGHVF 

API GUIDE v
LVFBDWWDFKBGDWDEDVH  ,6&B48$'VWUXFWXUH 
'3%VDQG  LVFBTXHBHYHQWV ²
LVFBEOREBGHIDXOWBGHVF  LVFBUROOEDFNBWUDQVDFWLRQ 
LVFBEOREBJHQBESE  LVFBVTOBLQWHUSUHWH ²
LVFBEOREBLQIR ² LVFBVTOFRGH 
LVFBEOREBORRNXSBGHVF  LVFBVWDUWBPXOWLSOH 
LVFBEOREBVHWBGHVF  LVFBVWDUWBWUDQVDFWLRQ YV 
LVFBFDQFHOBEORE  LVFBVWDUWBWUDQVDFWLRQ 
LVFBFDQFHOBHYHQWV  ,6&B67$786SRLQWHU 
LVFBFORVHBEORE  LVFBWUBKDQGOHW\SH 
LVFBFRPPLWBUHWDLQLQJ  LVFBWUDQVDFWLRQBLQIR 
LVFBFRPPLWBWUDQVDFWLRQ  ,6&B86(5HQYLURQPHQWYDULDEOH 
LVFBFUHDWHBEORE  LVFBYD[BLQWHJHU 
,6&B'$7$%$6(HQYLURQPHQWYDULDEOH  LVFBYHUVLRQ 
LVFBGDWDEDVHBLQIR  LVFBZDLWBIRUBHYHQW ²
LVFBGEBKDQGOHW\SH  LVRODWLRQOHYHOSDUDPHWHU 
LVFBGHFRGHBGDWH  UHVWULFWLYH 
LVFBGHWDFKBGDWDEDVH  LWHPW\SHFRQVWDQWV %/2%V 
LVFBGURSBGDWDEDVH  LWHPOLVWEXIIHU 
LVFBGVTOBDOORFDWHBVWDWHPHQW ² 6HHDOVRLVFBEOREBLQIR
LVFBGVTOBDOORFDWHBVWDWHPHQW 
LVFBGVTOBGHVFULEH 
LVFBGVTOBGHVFULEHBELQG  L
LVFBGVTOBH[HFBLPPHG  OLEUDULHV
LVFBGVTOBH[HFXWH ² %/2%ILOWHULQJURXWLQHV 
LVFBGVTOBH[HFXWHBLPPHGLDWH  G\QDPLFOLQN6HH'//V
LVFBGVTOBH[HFXWH  OLPERWUDQVDFWLRQV 
LVFBGVTOBIHWFK  OLQNLQJ 
6(/(&7VWDWHPHQWVDQG  ORFNUHVROXWLRQSDUDPHWHU 
LVFBGVTOBSUHSDUH ² ORJILOHV 
LVFBGVTOBVTOBLQIR DQG 
LVFBGVTOBVHWBFXUVRUBQDPH 
LVFBGVTOBVTOBLQIR ² M
LVFBHQFRGHBGDWH  PDFURV
LVFBHYHQWBEORFN  DFWLRQPHVVDJHV %/2%V 
LVFBHYHQWBFRXQWV ² $/,*1 
LVFBH[SDQGBGSE  GDWDW\SHV ;64/'$V ²
,6&B(;3257NH\ZRUG  LQIRUPDWLRQDO 64/ 
LVFBJHWBVHJPHQW  ;64/'$B/(1*7+ 
%/2%ILOWHUVDQG  PHPRU\
LVFBLQIRBWUXQFDWHGYDOXH  DOORFDWLQJ 
LVFBLQWHUSUHWH  UHWULHYLQJLQIRUPDWLRQDERXW 
LVFBRSHQBEORE  PHVVDJHV6HHHUURUPHVVDJHVVWDWXVPHVVDJHV
,6&B3$66:25'HQYLURQPHQWYDULDEOH  0LFURVRIW&&6HH&ODQJXDJH
LVFBSUHSDUHBWUDQVDFWLRQ  0LFURVRIW:LQGRZV6HH:LQGRZV
LVFBSUHSDUHBWUDQVDFWLRQ  PRQLWRULQJSHUIRUPDQFH 
LVFBSULQWBVTOHUURU  PXOWLGLPHQVLRQDODUUD\V 
LVFBSULQWBVWDWXV  GLPHQVLRQVUDQJH 
LVFBSXWBVHJPHQW  PXOWLSOHGDWDEDVHV
%/2%ILOWHUVDQG  DWWDFKLQJWR 

vi INTERBASE 5
 WUDQVDFWLRQVDQG  SDVVZRUGV 
6HHDOVRVHFXULW\
RYHUULGLQJ 
N VXSSO\LQJDWUXQWLPH 
1&+$59$5<,1*GDWDW\SH :LQGRZVFOLHQWV 
'64/DSSOLFDWLRQVDQG  3&GHYHORSPHQWHQYLURQPHQWV 
QHVWHGDUUD\V  SHUIRUPDQFHVWDWLVWLFV 
1HW:DUHVHUYHUV SHUIRUPDQFHPRQLWRULQJ 
%/2%ILOWHUVDQG  SRLQWHUV
XVHUQDPHVUHWXUQLQJ  6HHDOVRFXUVRUV
QHWZRUN'//V  ),/(VWUXFWXUH 
18//SRLQWHUV  WUDQVDFWLRQV 
18//VWDWXV  35(3$5( 
18//YDOXHV SURJUDPPLQJ
DUUD\VDQG  $3,DSSOLFDWLRQV ²
%/2%FROXPQV  '64/DSSOLFDWLRQV ²
%/2%KDQGOHV  HUURUKDQGOLQJ6HHHUURUV
H[WHQGHGGHVFULSWRUDUHDV  :LQGRZVDSSOLFDWLRQV 
QXPEHUV  SURWHFWLQJGDWD6HHVHFXULW\
DOLJQPHQWDGGUHVVHV 
E\WHRUGHULQJ 
SURFHVVLQJLQ;64/'$V  Q
180(5,&GDWDW\SH TXHULHV 
'64/DSSOLFDWLRQVDQG  6HHDOVR64/
QXPHULFYDOXHV6HHYDOXHV DUUD\VDQG 
'64/DSSOLFDWLRQV ²
O
2'66HHRQGLVNVWUXFWXUH R
RQGLVNVWUXFWXUH 5'%75$16$&7,216 
UHWULHYLQJLQIRUPDWLRQDERXW  UHDGLQJ%/2%GDWD ²
23(1  %/2%ILOWHUVDQG 
RSHQLQJ UHDGLQJGDWD ²
%/2%V  UHFRYHULQJGDWD 
FXUVRUV  UHTXHVWEXIIHUV ²""
RXWSXW GHILQHG 
HUURUPHVVDJHV  UHVHWWLQJ%/2%,'V 
RXWSXWGHVFULSWRUV6HH;64/'$V UHVXOWEXIIHUV ²""
RXWSXWILHOGV %/2%V ²
%/2%ILOWHUV  GHILQHG 
UHWULHYLQJGDWD 
'64/DSSOLFDWLRQV 
P VHOHFWHGURZV 
SDUDPHWHUV  UHYHUVLQJE\WHRUGHU 
'3%V  UROOEDFNV 
'64/VWDWHPHQWV  6HHDOVRWUDQVDFWLRQV
LQSXW  URXWLQHV
64/VWDWHPHQWV  %/2%ILOWHUV 
SURFHVVLQJZLWKQR ²² HUURUKDQGOLQJ 
WUDQVDFWLRQSDUDPHWHUEXIIHUV 73%V ² 64/ 

API GUIDE vii

URZPDMRURUGHUVSHFLI\LQJ  UHWULHYLQJVHOHFWOLVWLWHPV 
URZV VHOHFWLQJ%/2%GDWD ²
'64/DSSOLFDWLRQV  64/&2'(YDULDEOH
UHWULHYLQJLQIRUPDWLRQDERXW  '64/DSSOLFDWLRQV 
UXQWLPHHUURUV  UHWXUQYDOXHV 
VWDWHPHQWV
UHWULHYLQJ ²
S VWDWXVLQIRUPDWLRQ 
VHFXULW\ VWDWXVPHVVDJHV
DWWDFKPHQWUHTXLUHPHQWV  %/2%GDWD 
:LQGRZVFOLHQWV  WUDQVDFWLRQV 
6(/(&7 VWDWXVYHFWRUV6HHHUURUVWDWXVYHFWRUV
6HHDOVRVLQJOHWRQ6(/(&7V VWRULQJ
%/2%GDWDDQG ² %/2%GDWD 
6(/(&7VWDWHPHQWV GDWD 
DUUD\V ² VWULQJDGGUHVVHV
'64/DSSOLFDWLRQV  HUURUPHVVDJHV 
H[HFXWLQJ  VWULQJV6HHFKDUDFWHUVWULQJV
SUHSDULQJ  VXEVFULSWV DUUD\V 
UHWULHYLQJLQIRUPDWLRQDERXW  VZHHSLQJGDWDEDVHV
VLQJOHWRQ6(/(&7V  UHWULHYLQJLQIRUPDWLRQDERXW 
VHOHFWOLVWV  V\QFKURQRXVHYHQWV 
6HHDOVRTXHULHV UHTXHVWLQJQRWLILFDWLRQ 
%/2%GDWD  V\VWHPFUDVKHV 
GHILQHG  V\VWHPHUURUFRGHV 
SURFHVVLQJLWHPV 
UHWULHYLQJLWHPV 
6(775$16$&7,21 T
'64/DSSOLFDWLRQV  WDEOHQDPHV
VLJQHGQXPEHUV  VWRULQJ 
VLPXOWDQHRXVWUDQVDFWLRQV  WDEOHV
VLQJOHWRQ6(/(&7V DFFHVVLQJ ²
'64/DSSOLFDWLRQV  WHPSRUDU\GDWDEDVHV 
VRXQGILOHVVXSSRUWHG  WH[W
64/FOLHQWV  %/2%W\SHDQG 
64/GHVFULSWRUDUHDV H[WHQGHG 6HH;64/'$V WH[WILOHVVXSSRUWHG 
64/HUURUPHVVDJHV ² WLPHVWUXFWXUHV 
6HHDOVR64/&2'(YDULDEOH 73%V6HHWUDQVDFWLRQSDUDPHWHUEXIIHUV
EXLOGLQJ  WUDQVDFWLRQKDQGOHV ²
GLVSOD\LQJ  DVVLJQLQJDWUXQWLPH 
64/HUURUKDQGOLQJURXWLQHV  GHFODULQJ 
64/VWDWHPHQWV GHILQHG 
FRQYHUWLQJWRFKDUDFWHUVWULQJV  LQLWLDOL]LQJ 
FUHDWLQJ  WUDQVDFWLRQ,'V
'64/DSSOLFDWLRQVDQG ² WUDFNLQJ 
SDUDPHWHUVVXSSO\LQJYDOXHV  WUDQVDFWLRQSDUDPHWHUEXIIHUV 
H[HFXWLQJ  FRQVWDQWV 
QRQTXHU\VWDWHPHQWVDQG ² FUHDWLQJ ²
SURFHVVLQJ ²² GHIDXOW 
ZLWKQRSDUDPHWHUV ²² QXPHULFIRUPDWV 

viii INTERBASE 5
WUDQVDFWLRQV  6HHDOVR18//YDOXHV
DFFHVVPRGHV  QXPHULFGHVFULSWRUV 
DFFHVVLQJWDEOHV ² 9$5&+$5GDWDW\SH
FRPPLWWLQJ  '64/DSSOLFDWLRQVDQG 
H[HFXWLQJWZRSKDVHFRPPLWV  YDULDEOHOHQJWKGDWDSURFHVVLQJ 
UHWDLQLQJFRQWH[W  YHFWRUJUDSKLFILOHVVXSSRUWHG 
HQGLQJ  YHUVLRQQXPEHUV
HYHQWVDQG  GDWDEDVHV 
LVRODWLRQOHYHOV ² RQGLVNVWUXFWXUH 
OLPER  WUDQVDFWLRQSURFHVVLQJ 
ORFNLQJFRQIOLFWV  YLGHRILOHVVXSSRUWHG 
PXOWLSOHGDWDEDVHV  YLGHRVHJPHQWV 
RSWLPL]LQJ  YLHZV
UHIHUHQFLQJ  DUUD\VDQG 
UHWULHYLQJLQIRUPDWLRQDERXW 
UROOLQJEDFN 
VLPXOWDQHRXV  W
VSHFLI\LQJDWWULEXWHV ² :LQGRZVDSSOLFDWLRQV 
VWDUWLQJ  GHILQLQJGDWDW\SHV 
VWDWXVPHVVDJHV  HYHQWQRWLILFDWLRQ 
WUDQVDFWLRQH[LVWHQFHEORFNV 7(%V  VHWWLQJGHIDXOWGLUHFWRULHV 
WUDQVDFWLRQSDUDPHWHUEORFNV 73%V ² :LQGRZVFOLHQWV
WUDSV ² DWWDFKLQJ 
6HHDOVRHYHQWV HVWDEOLVKLQJSURJUDPSDUDPHWHUV 
VHFXULW\ 
ZULWLQJGDWD
U WRDUUD\V ²
XQNQRZQGDWDW\SHV  WR%/2%V 
XQNQRZQVWDWHPHQWV  %/2%ILOWHUVDQG 
83'$7(
DUUD\V ²
%/2%GDWD ² X
'64/DSSOLFDWLRQV  ;64/'$B/(1*7+PDFUR 
XSGDWLQJ ;64/'$V ²
DUUD\V ² 6HHDOVR;64/9$5VWUXFWXUH
%/2%GDWD ² DGGUHVVDOLJQPHQW 
XVHUQDPHV  FRHUFLQJGDWDW\SHV ²
RYHUULGLQJ  QXPEHUV 
UHWULHYLQJLQIRUPDWLRQDERXW  YDULDEOHOHQJWKGDWD 
VXSSO\LQJDWUXQWLPH  GHFODULQJ 
:LQGRZVFOLHQWV  ILHOGV 
XVHUGHILQHG%/2%ILOWHUV  LQSXWGHVFULSWRUV 
XVHUGHILQHGW\SHV DOORFDWLQJ 
%/2%GDWD  DUUD\V 
FUHDWLQJ 
RXWSXWGHVFULSWRUV 
V DOORFDWLQJ 
YDOXHSDUDPHWHUV FUHDWLQJ 
64/VWDWHPHQWV  UHVL]LQJ 
YDOXHV UHWULHYLQJ18//YDOXHV 

API GUIDE ix
 VHOHFWOLVWLWHPVDQG 
DUUD\V 
%/2%GDWD 
VHWWLQJ18//YDOXHV 
VSHFLI\LQJGDWDW\SHV ²
QXPEHUV 
YDULDEOHOHQJWKGDWD 
VWUXFWXUHV 
;64/9$5VWUXFWXUH 
DOORFDWLQJ 
DUUD\V 
%/2%GDWD 
GDWDW\SHV 
GHILQHG 
ILHOGV 
VHWWLQJXSVHOHFWOLVWLWHPV 

x INTERBASE 5