八、檔案操作函式
此版本支援的檔案操作函式有：
！CreateDirectory（strDirPath）
！FileAppend（strTarget，strSource）
！FileCopy（strSource，strTarget）
！FileDelete（strFilename）
！FileFind（strFilename，nameArr，sizeArr，attribArr）
！FileList（strPath，nameArr，sizeArr，attribArr）
！FileMove（strSource，strTarget）
！FileSplit（strSourceFile，strTargetFile，FileSize）
！GetFreeDiskSpace（）
！FileWriteByBuffer（filePath，filePos，bufID，bufPos，bufLength）
！FileReadByBuffer（filePath，filePos，dataLength，bufID，bufPos）
！FileWriteByStr（strFileName，strValue，mode，encode）
！FileReadByStr（strFilename，filePos，strLength，strResultRef，encode）
！GetFileSize（strFilePath）
注：
1。檔案操作涉及路徑均以“$MCGS_DIR_USER/”開始表示使用者目錄，以“$MCGS_DIR_HISTORY/”開始表示歷史資料目錄，其他情況則表示隨身碟目錄，且不能存在“。。/”、“/。。”、“/。。/”的路徑。
2。檔案操作涉及的路徑或檔名，在模擬環境下不區分大小寫；實際觸控式螢幕執行環境下嚴格區分大小寫。
3。若某個路徑下存在檔案時，在該路徑不能建立同名資料夾。因此，如果需要建立某個資料夾路徑時，若待建立的資料夾路徑中有同名的檔案存在，將會建立失敗。
！CreateDirectory（strDirPath）
函式意義：建立指定路徑的資料夾目錄
參 數：strDirPath，字串，輸入，目標目錄
返 回 值：整數
= 0，成功
失敗返回值：
= -209，輸入路徑錯誤
= -208，建立資料夾失敗
= -220，指定路徑中存在與待建立資料夾同名的檔案
= -1021，隨身碟未插入
實 例：ret = ！CreateDirectory（“$MCGS_DIR_USER/test/”），在$MCGS_DIR_USER下建立名為test的資料夾
！FileAppend（strSource，strTarget）
函式意義：將原始檔中的內容寫到目標檔案的末尾，使兩檔案的內容合併到目標檔案中
參 數：strSource，字串，輸入，原始檔路徑
strTarget，字串，輸入，目標檔案路徑
返 回 值：整數
= 0，成功
失敗返回值：
= -201，目標路徑與源路徑相同
= -203，讀寫失敗
= -204，開啟檔案失敗
= -205，磁碟空間不足
= -206，原始檔不存在
= -208，建立資料夾失敗
= -209，輸入路徑錯誤
= -220，目標路徑中存在與待建立資料夾同名的檔案
= -224，源路徑型別不匹配
= -225，目標路徑型別不匹配
= -1021，隨身碟未插入
實 例：ret = ！FileAppend（“$MCGS_DIR_USER/test/append/a。txt”，“$MCGS_DIR_USER/test/b。txt”），將$MCGS_DIR_USER/test/append下的檔案a。txt的內容寫到$MCGS_DIR_USER/test下的檔案b。txt的末尾。若b。txt不存在，則會自動新建一個檔案。
注意事項：strSource、strTarget不能為同一個檔案，否則返回目標路徑與源路徑相同；
！FileCopy（strSource，strTarget）
函式意義：將路徑為strSource的檔案複製到路徑為strTarget的檔案（支援資料夾複製）
參 數：strSource，字串，輸入，原始檔路徑
strTarget，字串，輸入，目標檔案路徑
返 回 值：整數
= 0，成功
失敗返回值：
= -201，目標路徑與源路徑相同
= -203，讀寫失敗
= -205，磁碟空間不足
= -206，原始檔或路徑不存在
= -208，建立資料夾失敗
= -209，輸入路徑錯誤
= -220，目標路徑中存在與待建立資料夾同名的檔案
= -227，源路徑為檔案，目標路徑下存在同名的資料夾
= -228，源路徑為資料夾，目標路徑為檔案或目標路徑下存在同名的檔案
= -229，目標路徑為源路徑的子資料夾
= -1021，隨身碟未插入
實 例：（1）ret = ！FileCopy（“$MCGS_DIR_USER/test/copySource/a。txt”，“$MCGS_DIR_USER/test/copy/b。txt”），將$MCGS_DIR_USER/test/copySource/的檔案a。txt複製到$MCGS_DIR_USER/test/copy/路徑下，且檔名為b。txt。
（2）ret = ！FileCopy（“$MCGS_DIR_USER/test/copySource/”，“$MCGS_DIR_USER/test/copy/”），將$MCGS_DIR_USER/test/copySource/下的所有檔案複製到$MCGS_DIR_USER/test/copy/copySource/路徑下。
（3）ret = ！FileCopy（“$MCGS_DIR_USER/test/copySource/a。txt”，“$MCGS_DIR_USER/test/copy/”），將$MCGS_DIR_USER/test/copySource/下的檔案a。txt複製到$MCGS_DIR_USER/test/copy/路徑下。
注意事項：1。若目標檔案已存在，則將目標檔案覆蓋
2。不能將資料夾複製至檔案，即strSource為資料夾路徑，strTarget為檔案路徑，將返回-228。
3。不能將檔案或資料夾複製至該檔案或資料夾當前所在的路徑下，即目標路徑為源路徑的上一級目錄，將返回-201。
！FileDelete（strFilename）
函式意義：將指定的檔案或目錄刪除
參 數：strFilename，字串，輸入，需要刪除的檔案或目錄
返 回 值：整數
= 0，成功
失敗返回值：
= -206，原始檔或路徑不存在
= -207，刪除檔案或資料夾失敗
= -209，輸入路徑錯誤
= -1021，隨身碟未插入
實 例：（1）ret = ！FileDelete（“$MCGS_DIR_USER/test/test。txt”），刪除$MCGS_DIR_USER/test/路徑下的檔案test。txt。
（2）ret = ！FileDelete（“$MCGS_DIR_USER/test/deleteDir/”），刪除$MCGS_DIR_USER/test/路徑下的資料夾deleteDir及資料夾內的所有檔案。
！FileFind（strFilename，nameArr，sizeArr，attribArr）
函式意義：查詢指定路徑下及子檔案下指定條件的檔案或資料夾
參 數：strFilename，字串，輸入，查詢條件：需要查詢的檔案或資料夾所在的路徑和條件（查詢條件中可以包含檔案萬用字元：*和？）
nameArr，字串陣列，輸出，函式呼叫成功後，儲存查詢結果的名稱（包含路徑）
sizeArr，整數陣列，輸出，函式呼叫成功後，儲存查詢結果的大小，單位：bit
attribArr，整數陣列，輸出，函式呼叫成功後，儲存查詢結果的屬性：0：表示檔案，1：表示資料夾，2：表示其它
返 回 值：整數
>=0，成功，返回查詢到滿足要求的結果的個數
失敗返回值：
= -206，源路徑不存在
= -209，輸入路徑錯誤
= -1021，隨身碟未插入
實 例：（1）ret = ！FileFind（“$MCGS_DIR_USER/test/find/a*”，nameArr，sizeArr，attribArr），查詢$MCGS_DIR_USER/test/find資料夾及子資料夾下名字第一個字母為a的檔案或目錄，將查詢結果的名字（包含路徑）存入nameArr字串陣列中，大小存入sizeArr整數陣列中，屬性存入attribArr整數陣列中。
（2）ret = ！FileFind（“$MCGS_DIR_USER/test/find/*”，nameArr，sizeArr，attribArr），查詢$MCGS_DIR_USER/test/find資料夾及子資料夾下所有的檔案或目錄，將查詢結果的名字（包含路徑）存入nameArr字串陣列中，大小存入sizeArr整數陣列中，屬性存入attribArr整數陣列中。
注意事項：strFilename必須以查條件結束，不能以”/”結束，否則結果返回0。
！FileList（strPath，nameArr，sizeArr，attribArr）
函式意義：獲取指定路徑下滿足條件的檔案和資料夾
參 數：strPath，字串，輸入，獲取條件：需要獲取的檔案或資料夾所在的路徑和條件（獲取條件中可以包含檔案萬用字元：*和？）
nameArr，字串陣列，輸出，函式呼叫成功後，儲存查詢結果的名稱
sizeArr，整數陣列，輸出，函式呼叫成功後，儲存查詢結果的大小，單位：bit
attribArr，整數陣列，輸出，函式呼叫成功後，儲存查詢結果的屬性：0：表示檔案，1：表示資料夾，2：表示其它
返 回 值：整數
>=0，成功，返回當前路徑下的檔案和資料夾總個數
失敗返回值：
= -206，源路徑不存在
= -209，輸入路徑錯誤
= -1021，隨身碟未插入
實 例：ret = ！FileList（“$MCGS_DIR_USER/test/find/”，nameArr，sizeArr，attribArr），獲取$MCGS_DIR_USER/test/find資料夾下的檔案和資料夾，將查詢結果的名字存入nameArr字串陣列中，大小存入sizeArr整數陣列中，屬性存入attribArr整數陣列中。
注意事項：若strPath為存在的資料夾路徑，則預設獲取條件為“*”，將獲取該資料夾下的檔案和資料夾的名稱、大小和屬性。
！FileMove（strSource，strTarget）
函式意義：將路徑為strSource的檔案移動並改名為路徑strTarget的檔案（支援資料夾移動）
參 數：strSource，字串，輸入，原始檔路徑
strTarget，字串，輸入，目標檔案路徑
返 回 值：整數
= 0，成功
失敗返回值：
= -201，目標路徑與源路徑相同
= -203，讀寫失敗
= -205，磁碟空間不足
= -206，原始檔或路徑不存在
= -208，建立資料夾失敗
= -209，輸入路徑錯誤
= -220，目標路徑中存在與待建立資料夾同名的檔案
= -226，目標路徑資料夾存在且不為空
= -227，源路徑為檔案，目標路徑下存在同名的資料夾
= -228，源路徑為資料夾，目標路徑為檔案或目標路徑下存在同名的檔案
= -229，目標路徑為源路徑的子資料夾
= -1021，隨身碟未插入
實 例：ret = ！FileMove（“$MCGS_DIR_USER/test/a。txt”，“$MCGS_DIR_USER/test/move/b。txt”）將$MCGS_DIR_USER/test下的檔案a。txt移動到$MCGS_DIR_USER/test/move並改名為b。txt。
注意事項：1。若目標檔案已存在，則將目標檔案覆蓋
2。資料夾移動至資料夾，若目標資料夾下存在與原始檔夾同名的資料夾且不為空時，返回-226，目標路徑資料夾存在且不為空；若目標資料夾下存在與原始檔夾同名的空資料夾，則會移動成功。
3。不能將資料夾移動至檔案，即strSource為資料夾路徑，strTarget為存在的檔案路徑，將返回-228。
4。不能將檔案或資料夾複製至路徑下，即目標路徑為源路徑的上一級目錄，將返回-201。
！FileSplit（strSourceFile，strTargetFile，FileSize）
函式意義：將指定檔案按指定大小分割為多個檔案
參 數：strSourceFile，字串，輸入，需要分割的檔名路徑
strTargetFile，字串，輸入，分割後的檔名
FileSize，整數，輸入，指定分隔後的檔案的最大大小，單位是MB
返 回 值：整數
> 0，成功，返回拆分後的檔案個數。
失敗返回值：
= -203，讀寫失敗
= -204，開啟檔案失敗
= -205，磁碟空間不足
= -206，原始檔或路徑不存在
= -209，輸入路徑錯誤
= -216，引數無效
= -221，原始檔路徑下存在與拆分後的檔案同名的資料夾
= -223，目標檔名輸入不合法
= -224，源路徑型別不匹配
= -1021，隨身碟未插入
實 例：ret = ！FileSplit（“$MCGS_DIR_USER/test/split。txt”，“new。txt”，1），將$MCGS_DIR_USER/test/下的檔案split。txt拆分為多個檔案，每個檔案最大為1MB，並存放在$MCGS_DIR_USER/test/下，分別命名為new000。txt、new001。txt、new003。txt、new004。txt等。
注意事項：1。strSourceFile不能為資料夾路徑，否則返回源路徑型別不匹配；
2。strTargetFile為拆分後的檔名，不能包含“/”，否則返回-223，目標檔名輸入不合法。
！GetFreeDiskSpace（）
函式意義：讀取空餘存檔空間
參 數：NA
返 回 值：整數
>=0，成功，返回空餘存檔空間值，單位MB
失敗返回值：
= -202，獲取磁碟資訊失敗
實 例：ret = ！GetFreeDiskSpace（），ret等於空餘存檔空間值。
！FileWriteByBuffer（filePath，filePos，bufID，bufPos，bufLength）
函式意義：將指定緩衝區指定位置開始的指定位元組長度的資料寫入指定的路徑的檔案的指定位置，覆蓋原有的內容
參 數：filePath，字串，輸入，檔案路徑，路徑不存在時直接建立
filePos，整數，輸入，指定檔案寫入的位置，-1表示寫入到檔案末尾
bufID，整數，輸入，唯一標識的緩衝區ID號
bufPos，整數，輸入，緩衝區位置（從0開始）
bufLength，整數，輸入，寫入檔案的緩衝區資料長度，-1表示指定位置開始的緩衝區所有的有效資料存入檔案
返 回 值：整數
> 0，成功，返回實際寫入檔案資料的大小
失敗返回值：
= -203，讀寫失敗
= -204，開啟檔案失敗
= -205，磁碟空間不足
= -208，建立資料夾失敗
= -209，輸入路徑錯誤
= -211，bufID無效
= -212，buffer不存在
= -213，訪問buffer越界
= -216，引數不正確
= -218，緩衝區位置超過有效資料位置
= -220，目標路徑中存在與待建立資料夾同名的檔案
= -225，目標路徑型別不匹配
= -1021，隨身碟不存在
實 例：！BufferCreate（1，100，ENDIAN_LITTLE，TEXT_UTF8），建立一個id為1，大小100，位元組序列小端，編碼格式“utf-8”的緩衝區；
（1）ret = ！FileWriteByBuffer（“$MCGS_DIR_USER/test/writeBuffer。txt”，0，1，5，10），將id為1的緩衝區，從5的位置開始，長度為10的資料寫到$MCGS_DIR_USER/test/writeBuffer。txt檔案偏移為0的位置，並返回10。
（2）ret = ！FileWriteByBuffer（“$MCGS_DIR_USER/test/writeBuffer。txt”，0，1，5，-1），將id為1的緩衝區，從5的位置開始，將緩衝區的資料全部寫到$MCGS_DIR_USER/test/writeBuffer。txt檔案偏移為0的位置，並返回緩衝區有效資料長度-5。
（3）ret = ！FileWriteByBuffer（“$MCGS_DIR_USER/test/writeBuffer。txt”，-1，1，5，-1），將id為1的緩衝區，從5的位置開始，將緩衝區的資料全部寫到$MCGS_DIR_USER/test/writeBuffer。txt檔案末尾的位置，並返回緩衝區有效資料長度-5。
注意事項：filePath不能為資料夾路徑，否則返回目標路徑型別不匹配。
！FileReadByBuffer（filePath，filePos，dataLength，bufID，bufPos）
函式意義：載入指定檔案指定位置開始的指定位元組長度的資料寫入指定的緩衝區的指定位置
參 數：filePath，字串，輸入，檔案路徑，檔案不存在時，載入失敗
filePos，整數，輸入，讀取指定檔案的位置
dataLength，整數，輸入，寫入緩衝區資料長度，-1表示檔案指定位置開始的全部的資料匯入緩衝區
bufID，整數，輸入，唯一標識的緩衝區ID號
bufPos，整數，輸入，緩衝區位置（從0開始）
返 回 值：整數
> 0，成功，返回匯入緩衝區資料的大小；若dataLength>0，且檔案位置加dataLength不超過檔案長度，返回dataLength，反之返回實際從檔案位置到檔案末尾的長度。
失敗返回值：
= -203，讀寫失敗
= -204，開啟檔案失敗
= -206，原始檔不存在
= -208，建立資料夾失敗
= -209，輸入路徑錯誤
= -211，bufID 無效
= -212，buffer不存在
= -213，訪問buffer越界
= -216，引數不正確
= -224，源路徑型別不匹配
= -230，檔案指定位置超過檔案總大小
= -1021，隨身碟不存在
實 例：！BufferCreate（1，100，ENDIAN_LITTLE，TEXT_UTF8），建立一個id為1，大小100，位元組序列小端，編碼格式“utf-8”的緩衝區；
（1）ret = ！FileReadByBuffer（“$MCGS_DIR_USER/test/writeBuffer。txt”，0，10，1，0），將$MCGS_DIR_USER/test/writeBuffer。txt檔案偏移為0的位置，長度為10的資料匯入id為1的緩衝區0的位置，返回10
（2）ret = ！FileReadByBuffer（“$MCGS_DIR_USER/test/writeBuffer。txt”，5，-1，1，0），將$MCGS_DIR_USER/test/writeBuffer。txt檔案偏移為5的位置開始到檔案末尾的資料全部匯入id為1的緩衝區0的位置，返回檔案大小減5（假設檔案可全部匯入緩衝區）。
注意事項：filePath不能為資料夾路徑，否則返回源路徑型別不匹配。
！FileWriteByStr（strFileName，strValue，mode，encode）
函式意義：將字串按照指定編碼方式寫入指定檔案的指定位置
參 數：strFileName，字串，輸入，檔案路徑，檔案不存在時建立
strValue，字串，輸入，需要寫入的字串
mode，列舉，輸入，寫入檔案的方式：追加或建立追加，FILE_APPEND：表示追加，FILE_TRUNC：表示新建
encode，列舉，輸入，設定字串的編碼格式，TEXT_UTF8：表示utf-8，TEXT_UTF16：表示utf-16，TEXT_GBK：表示gbk
返 回 值：整數，
>= 0，成功，返回寫入檔案的字串的長度
失敗返回值：
= -203，讀寫失敗
= -204，開啟檔案失敗
= -205，磁碟空間不足
= -208，建立資料夾失敗
= -209，輸入路徑錯誤
= -216，引數無效
= -220，目標路徑中存在與待建立資料夾同名的檔案
= -225，目標路徑型別不匹配
= -1021，隨身碟未插入
實 例：（1）ret = ！FileWriteByStr（“$MCGS_DIR_USER/test/writeStr。txt”，“strValue”，FILE_TRUNC，TEXT_UTF8），將字串“strValue”以utf-8的編碼方式，建立追加的方式寫入$MCGS_DIR_USER/test/writeStr。txt檔案中，返回字串utf-8編碼的長度8。
（2）ret = ！FileWriteByStr（“$MCGS_DIR_USER/test/writeStr。txt”，“strValue”，FILE_TRUNC，TEXT_UTF16），將字串“strValue”以utf-16的編碼方式，建立追加的方式寫入$MCGS_DIR_USER/test/writeStr。txt檔案中，返回字串utf-16編碼的長度16。
（3）ret = ！FileWriteByStr（“$MCGS_DIR_USER/test/writeStr。txt”，“strValue”，FILE_APPEND，TEXT_UTF16），將字串“strValue”以utf-16的編碼方式，追加的方式寫入$MCGS_DIR_USER/test/writeStr。txt檔案中，返回字串utf-16編碼的長度16。
注意事項：strFileName不能為資料夾路徑，否則返回目標路徑型別不匹配。
！FileReadByStr（strFilename，filePos，strLength，strResultRef，encode）
函式意義：從指定檔案指定位置開始，按照指定編碼方式讀取指定位元組的字串，或一整行，或全部字串並將結果儲存到strResultRef變數中
參 數：strFilename，字串，輸入，檔案路徑
filePos，整數，檔案位置
strLength，整數，輸入，獲取的字串長度，-1表示讀取從檔案指定位置到檔案末尾的全部字串；0表示從檔案指定位置開始讀取一行字串（即讀取到’\n’結束）；>0，表示從檔案指定位置開始讀取strLength個位元組。
strResultRef，字串引用，輸出，用於存放結果的字串變數
encode，列舉，輸入，設定字串的編碼格式，TEXT_UTF8：表示utf-8，TEXT_UTF16：表示utf-16，TEXT_GBK：表示gbk
返 回 值：整數
> 0，成功，若strLength=-1或strLength=0，則返回獲取的字串的長度；若strLength>0，且檔案位置加strLength不超過檔案長度，返回strLength，反之返回實際從檔案位置讀取到檔案末尾的長度。
失敗返回值：
= -203，讀寫失敗
= -204，開啟檔案失敗
= -206，原始檔或目錄不存在
= -209，輸入路徑錯誤
= -216，引數無效
= -224，源路徑型別不匹配
= -230，檔案指定位置超過檔案總大小
= -1021，隨身碟未插入
實 例：（1）ret = ！FileReadByStr（“$MCGS_DIR_USER/test/readStr。txt”，0，10，strResultRef，TEXT_UTF16），從$MCGS_DIR_USER/test/路徑下的檔案readStr。txt的檔案偏移為0位置開始，按照utf-16的編碼方式讀取10位元組的字串，將結果儲存到strResultRef變數中，返回10。
（3）ret = ！FileReadByStr（“$MCGS_DIR_USER/test/readStr。txt”，0，10，strResultRef，TEXT_UTF8），從$MCGS_DIR_USER/test/路徑下的檔案readStr。txt的檔案偏移為0位置開始，按照utf-8的編碼方式讀取10位元組的字串，將結果儲存到strResultRef變數中，返回10。
（3）ret = ！FileReadByStr（“$MCGS_DIR_USER/test/readStr。txt”，6，-1，strResultRef，TEXT_UTF16），從$MCGS_DIR_USER/test/路徑下的檔案readStr。txt的檔案偏移為6位置開始，按照utf-16的編碼方式讀取到檔案末尾的字串，將結果儲存到strResultRef變數中，返回檔案大小減6。
（4）ret = ！FileReadByStr（“$MCGS_DIR_USER/test/readStr。txt”，6，0，strResultRef，TEXT_UTF16），從$MCGS_DIR_USER/test/路徑下的檔案readStr。txt的檔案偏移為6位置開始，按照utf-16的編碼方式讀取到當前行的末尾的字串，將結果儲存到strResultRef變數中，返回實際讀取到字串的長度。
注意事項：strFileName不能為資料夾路徑，否則返回源路徑型別不匹配。
！GetFileSize（strFilePath）
函式意義：獲取指定檔案的大小
參 數：strFilePath，字串，輸入，檔案路徑
返 回 值：整數
>=0，成功，返回獲取到的檔案大小，單位：位元組
失敗返回值：
= -206，原始檔不存在
= -209，輸入路徑錯誤
= -1021，隨身碟未插入
實 例：ret = ！GetFileSize（“$MCGS_DIR_USER/test/testFile。txt”），獲取$MCGS_DIR_USER/test/路徑下的檔案testFile。txt的大小，返回檔案大小。
注意事項：strFilePath不能為資料夾，否則返回輸入路徑錯誤。