這篇文章演示了如何用其他語言（如C，C 或Java）編寫的代碼插入到Stata中。這種技術(shù)被稱為Stata編寫插件或編寫動(dòng)態(tài)鏈接庫(kù)（DLL）。本文中，在C語言中編寫一個(gè)插件，它實(shí)現(xiàn)了mymean11.ado中mymean_work（）執(zhí)行的計(jì)算，在文章在Stata中編寫估計(jì)命令編寫插件中討論過。
編寫一個(gè)hello-world C插件
在進(jìn)行任何計(jì)算之前，先說明如何編寫和編譯與Stata通信的C插件。Code block 1包含myhello.ado的代碼，該代碼調(diào)用C插件hello，它只顯示Stata中的“Hello from C”。
第6行執(zhí)行句柄hello的插件。第10行將hello.plugin中實(shí)現(xiàn)的插件加載到句柄hello中。執(zhí)行語句在加載語句開始出現(xiàn)之前就是奇數(shù)。完整地讀取Stata ado文件，并且在執(zhí)行主要ado程序行之前加載每個(gè)ado程序，Mata函數(shù)或插件句柄。所以第10行實(shí)際上是在第6行之前執(zhí)行的。
插件的句柄名稱，本例中的hello，必須與主要ado程序的名稱，本例中的myhello以及此.ado文件中定義的任何其他ado程序不同。
Code block 2中的hello.c的代碼。
第2行包括Stata插件頁眉文件stplugin.h。第6行是Stata C插件入口函數(shù)的標(biāo)準(zhǔn)聲明。您應(yīng)該復(fù)制它。在stata_call()中，argc將包含傳遞給插件的參數(shù)數(shù)量，字符串向量argv將包含參數(shù)本身。
第8行聲明并為C字符串msg分配空間。第10行將“Hello from C”中的新行添加到msg中。第11行有Stata顯示msg包含的內(nèi)容。12行將0作為返回碼。請(qǐng)注意，我將文字0轉(zhuǎn)換為預(yù)期類型ST_retcode。
現(xiàn)在討論如何從hello.c創(chuàng)建插件hello.plugin。在包含myhello.ado和hello.c的目錄中，我也有stplugin.c。stplugin.c定義了一個(gè)函數(shù)，使stata_call（）函數(shù)對(duì)Stata可用。
不要更改stplugin.h或stplugin.c的內(nèi)容。事實(shí)上，您甚至不需要看它們。
在安裝了命令行開發(fā)工具的OS X Mac上，使用gcc通過輸入stplugin.c和hello.c來創(chuàng)建hello.plugin，
gcc -bundle -DSYSTEM=APPLEMAC stplugin.c hello.c -o hello.plugin
上面的gcc命令編譯兩個(gè).c文件并鏈接它們以創(chuàng)建myhello.ado可以調(diào)用的DLL hello.plugin。
在本文的附錄中，我提供了在其他平臺(tái)上創(chuàng)建hello.plugin的說明。
創(chuàng)建了hello.plugin后，就可以在Stata中執(zhí)行myhello。
示例1：myhello
為簡(jiǎn)單起見，我將stplugin.h，stplugin.c，hello.c，myhello.ado和hello.plugin放在同一目錄中。對(duì)于較大的項(xiàng)目，我會(huì)將.ado和.plugin文件放在Stata的ADOPATH目錄中，并使用我的編譯器環(huán)境來管理我放置標(biāo)題和C源文件的位置。 對(duì)于這篇文章中的示例，我將所有.ado文件，頭文件，C源文件和創(chuàng)建的.plugin文件放入一個(gè)目錄中。
訪問插件中的Stata數(shù)據(jù)
hello.plugin使Stata顯示在插件中創(chuàng)建的內(nèi)容。下一步是讓插件訪問Stata中的數(shù)據(jù)。 為了說明這個(gè)過程，我討論了mylistc.ado，它使用插件列出指定變量的觀察結(jié)果。
我們先來看一下ado-code。
第6行中，syntax創(chuàng)建了三個(gè)本地宏。它將用戶指定的變量放入本地宏varlist中。它將用戶指定的任何if條件放入本地宏if。將用戶指定的任何條件放入本地宏in中。為syntax指定了max = 3以將變量數(shù)量限制為3。我不需要它作為Stata / Mata程序示例，但它簡(jiǎn)化了示例C插件。
第7行中，marksample創(chuàng)建了一個(gè)樣本包含變量，并將其名稱放在本地宏touse中。樣本包含變量對(duì)于每一個(gè)被排除的觀察和每個(gè)被包含的觀察都是0。marksample使用本地宏varlist中的變量，本地宏中的if的條件，以及本地宏in中的范圍來創(chuàng)建樣本包含變量。 （所有三個(gè)本地宏由syntax創(chuàng)建。）如果本地宏varlist中的任何變量包含缺失值，如果被本地宏if的條件排除，或者被本地宏in的范圍排除，則排除觀察。樣本包含變量是未被排除的觀測(cè)值之一。
第9行中，通過顯示插件列出的值的變量名稱進(jìn)一步簡(jiǎn)化了C插件。
第10行，plugin調(diào)用mylistw.plugin。因?yàn)橹付?varlist'，所以Stata插件接口（SPI）函數(shù)SF_vdata（）能訪問本地宏varlist中包含的變量。因?yàn)槿绻付薫touse'，如果`touse'中的樣本包含變量為0，則SPI函數(shù)SF_ifobs（）將返回0，如果樣本包含變量為1，則函數(shù)將返回1。由于指定了“in”，因此SPI函數(shù)SF_in1（）和SF_in2（）分別返回范圍內(nèi)任何用戶指定的第一個(gè)和最后一個(gè)觀察值。
指定“in”不是識(shí)別用戶指定樣本所必需的，因?yàn)槿绻鸴touse'已經(jīng)指定了此樣本包含信息。 但是，指定“in”可以顯著減少數(shù)據(jù)循環(huán)中的觀察范圍，從而加快代碼速度。
在包含stplugin.h，stplugin.c和mylistw.c的目錄中，通過鍵入以下代碼在Mac上創(chuàng)建了mylistw.plugin
gcc -bundle -DSYSTEM=APPLEMAC stplugin.c mylistw.c -o mylistw.plugin
如果你正在閱讀這篇文章，你可以閱讀標(biāo)準(zhǔn)C。我討論了mylistw.c如何說明Stata C插件的結(jié)構(gòu)，并解釋了代碼中使用的SPI定義的類型和函數(shù)。
如果一切順利，mylistw.c會(huì)向Stata返回0，如果出錯(cuò)，會(huì)返回一個(gè)非0錯(cuò)誤的代碼。 每當(dāng)在mylistw.c中調(diào)用一個(gè)可能失敗的函數(shù)時(shí)，我都會(huì)檢查它的返回碼。如果該函數(shù)失敗，我會(huì)讓Stata顯示錯(cuò)誤消息，并向Stata返回非0錯(cuò)誤代碼。 該邏輯為mylisw.c提供了整體結(jié)構(gòu)。大多數(shù)代碼處理錯(cuò)誤條件或者注意不要在字符串緩沖區(qū)中放入超出其容量的字符。
C插件使用SPI中定義的函數(shù)讀取或?qū)懭隨tata對(duì)象。mylistw.c不會(huì)返回任何結(jié)果，因此它具有簡(jiǎn)單的結(jié)構(gòu)。
. 使用SPI函數(shù)從Stata中指定的數(shù)據(jù)樣本中讀取數(shù)據(jù)。
. 使用標(biāo)準(zhǔn)C和SPI函數(shù)列出指定樣本的觀察值，并保留指定樣本中觀察數(shù)量的計(jì)數(shù)器。
. 使用標(biāo)準(zhǔn)的C和SPI函數(shù)來顯示樣本中的第一個(gè)觀察結(jié)果，這是樣本中的最后一個(gè)觀察結(jié)果，以及指定樣本中有多少觀察結(jié)果。
現(xiàn)在，我將討論mylistw.c的具體部分。
在9-12行中，使用SPI定義的類型ST_int，ST_double和ST_retcode來處理SPI函數(shù)返回的變量或SPI函數(shù)的參數(shù)。 使用這些定義的類型是必不可少的，因?yàn)樗鼈兣c原始C類型的映射會(huì)隨著時(shí)間而變化。
rc保存插件將返回到Stata的返回代碼。在16行，我將rc初始化為0。如果SPI函數(shù)可能會(huì)失敗，那么它會(huì)返回0的返回碼。如果SPI函數(shù)無法執(zhí)行請(qǐng)求，則返回的是非0返回碼。每次調(diào)用可能失敗的SPI函數(shù)時(shí)，我都會(huì)將它返回的代碼存儲(chǔ)在rc中。如果rc不是0，我會(huì)讓Stata顯示錯(cuò)誤消息并使插件返回存儲(chǔ)在rc中的非0值。
第18,20和22行使用SPI功能。SF_in1（）將in范圍指定的第一個(gè)觀察值放入first。SF_in2（）將in范圍內(nèi)指定的最后一個(gè)觀察值放入last。如果沒有為plugin指定in范圍，則first包含1，last將包含數(shù)據(jù)集中的觀察數(shù)。SF_nvars（）將varlist中指定的變量數(shù)放入nVars。
第30-32行確保我們跳過mylistc.ado第10行中為插件指定的if限制所排除的觀察結(jié)果。為了說明一些細(xì)節(jié)，請(qǐng)參考示例2。
示例2：mylistc
在第30行中，對(duì)于觀察值i來說，當(dāng)為plugin指定的if限制為1，SF_ifobs（i）返回1，否則返回0。在mylist.ado的第10行中，我們看到傳入plugin的if限制是“touse”。如上所述，本地宏touse的樣本包含變量對(duì)于排除的觀察值是0，對(duì)于包括的觀察值是1。
在mylistc.ado第10行的范圍內(nèi)，使mylistw.c第27行中循環(huán)的觀察結(jié)果只能從范圍內(nèi)任何指定的開始到結(jié)束。在示例2中，mylistw.c的第27行上的循環(huán)從2到10，而不是在自動(dòng)數(shù)據(jù)集上對(duì)所有74個(gè)觀察結(jié)果進(jìn)行循環(huán)。
在示例2中，樣本包含變量對(duì)于6個(gè)觀察值為1，對(duì)于其他68個(gè)觀察值為0。在in 2/10范圍內(nèi)不包括觀察結(jié)果1和11-74的觀察結(jié)果。 在前10個(gè)觀察中，2個(gè)被排除，因?yàn)槿鄙賠ep78。 排除一個(gè)觀察因?yàn)閠runk是21。
為了比較，在示例3中列出了2和10之間的所有9個(gè)觀察結(jié)果。
案例3：list
返回mylistw.c的第38行，rc = SF_vdata（j，i，＆value）將觀察值i放在變量j上，它將SF_vdata（）返回的代碼放入rc。 如果一切順利，rc包含0，并且不輸入第41-43行中的錯(cuò)誤塊。 如果SF_vdata（）無法將數(shù)據(jù)存儲(chǔ)到value中，則會(huì)輸入 第41-43行中的錯(cuò)誤塊，這會(huì)使Stata顯示錯(cuò)誤消息并導(dǎo)致mylistw.plugin以rc包含的錯(cuò)誤代碼退出。在錯(cuò)誤塊中，SF_error（）使Stata以紅色顯示C字符串的內(nèi)容。
SF_vdata（）只能訪問一個(gè)數(shù)字Stata數(shù)據(jù)類型（byte，int，long，float或double）的變量。（對(duì)于字符串?dāng)?shù)據(jù)使用SF_sdata（）。）無論變量是哪個(gè)Stata數(shù)字類型，SF_vdata（）都將結(jié)果存儲(chǔ)為ST_double。 在示例2中，mpg，trunk，rep78在Stata中都是int類型，但每個(gè)都作為ST_double存儲(chǔ)到value中。
第46行，如果value是缺失值，則SF_is_missing（value）返回1，否則返回0。如果其中一個(gè)變量中的任何觀察值包含缺失值，則第46-50行導(dǎo)致mlistw.plugin以錯(cuò)誤416退出。這些行是多余的，因?yàn)閭鬟f到mylistw.plugin的樣本包含變量排除了包含缺失值的觀察。 我包含這些行是來說明如何安全地從插件中排除缺失值并重申C代碼必須小心處理缺失值。 Stata缺失值在C代碼中的是有效的雙精度數(shù)。如果在計(jì)算中包含Stata缺失值，則會(huì)得到錯(cuò)誤的結(jié)果。
剩余的行構(gòu)造C字符串行，傳遞給Stata以顯示每個(gè)觀察結(jié)果，最后顯示有關(guān)樣本的摘要信息。
C語言插件中的均值估計(jì)
我現(xiàn)在討論ado-命令mymeanc，它使用mycalcs.plugin實(shí)現(xiàn)mymean_work（）執(zhí)行的計(jì)算，在Programming an estimation command in Stata: Preparing to write a plugin中有討論mymean11.ado。
mymeanc的代碼位于mymeanc.ado中，在下面代碼塊5中。
該程序的一般結(jié)構(gòu)與mymean10.ado和mymean11相同，在Programming an estimation command in Stata: Preparing to write a plugin中討論過。 從全局角度來看，mymeanc.ado：
. 解析用戶輸入；
. 創(chuàng)建一些名稱和對(duì)象來保存結(jié)果；
. 調(diào)用工作程序來進(jìn)行計(jì)算；
. 將工作程序返回的結(jié)果存儲(chǔ)在e（）中；
. 顯示結(jié)果.
mymeanc.ado和mymean11.ado之間的主要區(qū)別在于工作程序是C插件而不是Mata函數(shù)。
第6行和第7行與mylistc.ado中的相同。有關(guān)這些行如何創(chuàng)建本地宏varlist的說明，本地宏touse中包含的樣本包含變量以及包含任何用戶指定范圍的本地宏，請(qǐng)參閱Getting access to the Stata data in your plugin中mylistc.ado的討論。
第8行將臨時(shí)名稱放入本地宏b，V和N中。我們將這些名稱用于C插件計(jì)算的結(jié)果，并知道不會(huì)覆蓋用戶存儲(chǔ)在全局Stata內(nèi)存中的任何結(jié)果。（回想一下，Stata矩陣和標(biāo)量是Stata中的全局對(duì)象；Using temporary names for global objects in Programming an estimation command in Stata: A first ado-command文中有討論本話題。）另外，此外，當(dāng)mymeanc終止時(shí)，Stata將刪除tempname創(chuàng)建的臨時(shí)名稱中的對(duì)象。
第10-12行創(chuàng)建Stata矩陣來保存結(jié)果。我們使用tempname為這些矩陣創(chuàng)建臨時(shí)名稱。
mymeanc.ado中的第14行類似于mylistc.ado中第10行的對(duì)應(yīng)部分。在這種情況下，插件調(diào)用mycalcs.plugin來完成工作。 varlist的細(xì)節(jié)，`if' `touse' 和 `in'在上面討論過。 最新的是我們將參數(shù)`b'`V'`N'將臨時(shí)名稱傳遞給mycalcs.plugin。
mycalcs.plugin
. 做計(jì)算
. 估計(jì)均值放入Stata矩陣中，該矩陣的名稱在本地宏b中
. 估計(jì)量的估計(jì)方差（VCE）放入名稱在本地宏V中的Stata矩陣中
. 樣本中的觀察數(shù)量放入名稱在本地宏N中的Stata標(biāo)量中
16-18行將變量名稱放在估計(jì)均值向量的列條帶上以及VCE矩陣的行和列條帶上。 第19-21行將結(jié)果存儲(chǔ)在e（）中。 在第22行顯示結(jié)果。
現(xiàn)在討論創(chuàng)建mycalcs.plugin的代碼。 在討論細(xì)節(jié)之前，我們創(chuàng)建插件并運(yùn)行一個(gè)例子。
在包含mycalcs.c，mycalcsw.h，mycalcsw.c，stplugin.c和stplugin.h的目錄中，通過輸入以下代碼在Mac上創(chuàng)建mycalcs.plugin
gcc -bundle -DSYSTEM=APPLEMAC stplugin.c mycalcsw.c mycalcs.c -o mycalcs.plugin
創(chuàng)建mycalcs.plugin后，運(yùn)行示例3。
示例3：mymeanc
現(xiàn)在討論用于創(chuàng)建mycalcs.plugin的C代碼的一些方面。 從代碼塊6中的mycalcs.c開始，包含入口函數(shù)stata_call（）的代碼。
總之，mycalcs.c中的代碼執(zhí)行以下任務(wù)。
它將作為參數(shù)傳入的Stata對(duì)象名稱放入可以傳遞給工作函數(shù)的C字符串中。
它使用工作函數(shù)InitCmat（）為C數(shù)組bmat和vmat分配空間，以保存矩陣結(jié)果。
它使用工作函數(shù)MyAve（）和MyV（）來計(jì)算存儲(chǔ)在bmat，vmat和nObs中的結(jié)果。
它使用工作函數(shù)CopyCtoStataMatrix（）和SPI函數(shù)SF_scal_save（）從bmat，vmat和nObs中將結(jié)果復(fù)制到在步驟1中解析其名稱的Stata對(duì)象中。
它釋放分配的C數(shù)組并返回返回代碼。
mycalcs.c很容易閱讀，因?yàn)槲覍⑺屑?xì)節(jié)都放入了工作函數(shù)中。這些函數(shù)是在mycalcsw.c中定義，在下面我們將討論它們。
與mylistw.c一樣，mycalcs.c使用返回代碼rc來處理錯(cuò)誤情況。如果一切順利，則每個(gè)工作函數(shù)返回0，如果無法執(zhí)行所請(qǐng)求的作業(yè)，則返回非0錯(cuò)誤代碼。 如果返回代碼不為0，mycalcs.c會(huì)進(jìn)入一個(gè)代碼塊來處理錯(cuò)誤。每個(gè)錯(cuò)誤塊使Stata顯示錯(cuò)誤消息，它釋放任何已分配的C數(shù)組，最后，導(dǎo)致stata_call（）返回非0代碼。
現(xiàn)在在Code block 7中討論mycalcsw.c中的工作函數(shù)。
如何在C數(shù)組中實(shí)現(xiàn)矩陣的兩個(gè)方面值得討論。首先，將矩陣存儲(chǔ)為具有行主要存儲(chǔ)的向量，正如第7-10行的注釋中所提到的那樣。 其次，使用第14-18行定義的預(yù)處理器宏來使代碼更易于閱讀。 請(qǐng)注意，在第166-169行上未定義這些宏。
除了使用SF_error（）使Stata顯示錯(cuò)誤消息，如果malloc（）不能分配內(nèi)存，工作函數(shù)InitCmat（）使用標(biāo)準(zhǔn)C來實(shí)現(xiàn)矩陣分配和初始化函數(shù)。
工作函數(shù)MyAve（）是在Mata中實(shí)現(xiàn)的MyAve（）的C實(shí)現(xiàn)，詳見: Programming an estimation command in Stata: Preparing to write a plugin。當(dāng)我討論mylistw.c時(shí)，如上所述，MyAve（）處理Stata數(shù)據(jù)和缺失值。在第71行調(diào)用的工作函數(shù)DivideByScalar（），通過存儲(chǔ)在n中的樣本觀察數(shù)劃分bmat中的每個(gè)元素。（強(qiáng)制轉(zhuǎn)換可確保執(zhí)行浮點(diǎn)而不是整數(shù)除法。）
工作函數(shù)MyV（）是在Mata中實(shí)現(xiàn)的MyV（）的C實(shí)現(xiàn)，參考Programming an estimation command in Stata: Preparing to write a plugin。MyV（）使用到目前為止討論的大多數(shù)編碼技術(shù)和函數(shù)。 此函數(shù)比其他函數(shù)更長(zhǎng)，但其中的所有內(nèi)容都是標(biāo)準(zhǔn)C或我已經(jīng)討論過的內(nèi)容。
工作函數(shù)CopyCtoStataMatrix（）將結(jié)果從C數(shù)組復(fù)制到Stata矩陣。使用SF_mat_store（smat，（i 1），（j 1），C（i，j））將元素從C數(shù)組的第i行和第j列復(fù)制到Stata矩陣中的相應(yīng)元素。Stata矩陣元素被指定為（i 1）和（j 1），因?yàn)樵诖a中的C矩陣使用基于零開始的索引，而SF_mat_store（）使用基于一個(gè)索引的Stata矩陣元素。
工作函數(shù)Divide By Scalar（）用標(biāo)量劃分C數(shù)組中的每個(gè)元素。
為了完整起見，我現(xiàn)在討論mycalcsw.h。 代碼塊8中給出的mycalcsw.h包含mycalcsw.c中定義的工作函數(shù)的函數(shù)原型。
完成和撤消
我展示了如何實(shí)現(xiàn)一個(gè)C插件，該插件執(zhí)行mymean10.ado和mymean11.ado中Mata工作函數(shù)執(zhí)行的計(jì)算，如程序29中所述。
附錄
在文中，我展示了如何使用命令行開發(fā)工具編譯和鏈接一個(gè)OS 10 MAC的插件。 在這里，我在Windows 10和RedHat Linux上為gcc編譯器提供命令。
Windows 10
本小節(jié)提供了在64位Windows 10系統(tǒng)上編譯和鏈接Cygwin環(huán)境中插件的命令。與其他平臺(tái)不同，我們不能只使用gcc。在Cygwin中，gcc編譯應(yīng)用程序以在Cygwin POSIX / Unix環(huán)境中運(yùn)行。我們希望使用Cygwin編譯一個(gè)鏈接到本機(jī)Windows應(yīng)用程序并在其中運(yùn)行的庫(kù)。 Cygwin擁有適用于Windows（MinGW）的極簡(jiǎn)的GNU編譯器，可以滿足我們的需求。 相應(yīng)編譯器的名稱取決于平臺(tái)。在64位x86-Intel機(jī)器上，我使用了x86_64-w64-mingw32-gcc編譯器。
hello.plugin
在包含stplugin.h，stplugin.c和hello.c的目錄中，通過鍵入以下命令來創(chuàng)建hello.plugin：
x86_64-w64-mingw32-gcc -shared -mno-clwb stplugin.c hello.c -o hello.plugin
mylistw.plugin
在包含stplugin.h，stplugin.c和mylistw.c的目錄中，通過鍵入以下命令來創(chuàng)建mylistw.plugin：
x86_64-w64-mingw32-gcc -shared -mno-clwb stplugin.c mylistw.c -o mylistw.plugin
mycalcs.plugin
在包含stplugin.c，stplugin.h，mycalcs.c，mycalcsw.h和mycalcsw.c的目錄中，通過鍵入以下命令來創(chuàng)建mycalcs.plugin：
x86_64-w64-mingw32-gcc -shared -mno-clwb stplugin.c mycalcsw.c mycalcs.c -o mycalcs.plugin
RedHat Linux
本小節(jié)提供了在RedHat Linux上編譯和鏈接插件的gcc命令。
hello.plugin
在包含stplugin.h，stplugin.c和hello.c的目錄中，通過鍵入以下命令來創(chuàng)建hello.plugin：
gcc -shared -fPIC -DSYSTEM=OPUNIX stplugin.c hello.c -o hello.plugin
mylistw.plugin
在包含stplugin.h，stplugin.c和mylistw.c的目錄中，通過鍵入以下命令來創(chuàng)建mylistw.plugin：
gcc -shared -fPIC -DSYSTEM=OPUNIX stplugin.c mylistw.c -o mylistw.plugin1
mycalcs.plugin
在包含stplugin.c，stplugin.h，mycalcs.c，mycalcsw.h和mycalcsw.c的目錄中，通過鍵入以下命令來創(chuàng)建mycalcs.plugin：
gcc -shared -fPIC -DSYSTEM=OPUNIX stplugin.c mycalcsw.c mycalcs.c -o mycalcs.plugin
