tSysFileOpen (STRUCT) ¶ TYPE tSysFileOpen : STRUCT Parameter to open a file asynchronously InOut: Name Type Comment szFile STRING(254) File name. File name can contain an absolute or relative path to the file. Path entries must be separated with a Slash (/) and not with a Backslash (\)! am ACCESS_MODE Requested access mode to the file. See |ACCESS_MODE| for details. Here find some examples: AM_READ If file does not exist, an error is returned. If the file exists, the file will be opened AM_WRITE If file does not exist, a new file will be created. If the file exists, it will be overwritten! AM_APPEND If the file does not exist, an error is returned. If the file exists, the file will be opened pResult POINTER TO RTS_IEC_RESULT [OUT] Pointer to the runtime system error code (see CmpErrors2 Interface Library) pulOut POINTER TO RTS_IEC_HANDLE [OUT] Handle to the file or RTS_INVALID_HANDLE if failed
tSysFileRead (STRUCT) ¶ TYPE tSysFileRead : STRUCT Parameter to read a file asynchronously InOut: Name Type Comment pbyBuffer POINTER TO BYTE Pointer to buffer for read data ulSize __XWORD Number of bytes to read from file. Must be less or equal the buffer size! pResult POINTER TO RTS_IEC_RESULT [OUT] Pointer to the runtime system error code (see CmpErrors2 Interface Library) pulOut POINTER TO __XWORD [OUT] Number of bytes read from file. 0=if failed
tSysFileRename (STRUCT) ¶ TYPE tSysFileRename : STRUCT Parameter to rename a file asynchronously InOut: Name Type Comment szOldName STRING(254) Old file name. File name can contain an absolute or relative path to the file. Path entries must be separated with a Slash (/) and not with a Backslash (\)! szNewName STRING(254) New file name. File name can contain an absolute or relative path to the file. Path entries must be separated with a Slash (/) and not with a Backslash (\)! pulOut POINTER TO RTS_IEC_RESULT [OUT] Pointer to the runtime system error code (see CmpErrors2 Interface Library)
tSysFileSetPos (STRUCT) ¶ TYPE tSysFileSetPos : STRUCT Parameter to set a position in a file asynchronously InOut: Name Type Comment ulOffset __XWORD Offset to set from the beginning of the file pulOut POINTER TO RTS_IEC_RESULT [OUT] Pointer to the runtime system error code (see CmpErrors2 Interface Library)
tSysFileWrite (STRUCT) ¶ TYPE tSysFileWrite : STRUCT Parameter to write a file asynchronously InOut: Name Type Comment pbyBuffer POINTER TO BYTE Pointer to buffer with data to write to file ulSize __XWORD Number of bytes to write in the file. Must be less or equal the buffer size! pResult POINTER TO RTS_IEC_RESULT [OUT] Pointer to the runtime system error code (see CmpErrors2 Interface Library) pulOut POINTER TO __XWORD [OUT] Number of bytes written to the file. 0=if failed
Documentation (GVL) ¶ General Information: ¶ All asynchronous system libraries are only asynchronous wrappers around their underlaying System-Library. So this library is only an asynchronous wrapper around the SysFile.library. The asynchronous functions are named as the correspnding function in the base library, but only with the ending <SysFunction>Async. Every asynchronous system function is included in one function block, with the ending <SysLib>AsyncFB. This FB must be instantiated to use all asynchonous methods. Each asynchronous method has 3 parameters: <SysFunction>: Pointer to the parameter structure (see below) pudState: Pointer on current status of the asynchonous action: ASYNCSTATE_INVALID : UDINT := 16#FFFFFFFF ; ASYNCSTATE_PENDING : UDINT := 0 ; ASYNCSTATE_ACTIVE : UDINT := 1 ; ASYNCSTATE_READY : UDINT := 2 ; ASYNCSTATE_ERROR : UDINT := 3 ; ASYNCSTATE_TIMEOUT : UDINT := 4 ; The status at starting the asynchronous job always is ASYNCSTATE_INVALID . pResult: Pointer to runtime system error code (see CmpErrors.library) Each asynchonous method gets the same parameter as the base system library, but they are collected to one parameter structure. The name of this parameter structure has always the prefix “t”: t<SysFunction> For a description of the particular function parameters please see the chapters on the corresponding functions in the documentation on the System-Base library (<SysLib>.library). When calling the asynchronous method, the asynchronous job gets started. The job will be finished as soon as the status has got one of the following three values: ASYNCSTATE_READY : Job successfully finished ASYNCSTATE_ERROR : Job terminated with error ASYNCSTATE_TIMEOUT : Job timeout reached before job could be finished successfully The last parameter in the parameter structure contains always the result of the base system function indicating whether the asynchronous job could be finished successfully of not. The result value of each asynchronous method is the handle of the asynchronous job. By use of this handle and the functions of the library CmpAsyncMgr.library further information on the asynchronous job can be retrieved. USAGE of the FB: ¶ Before first use of the function block, you have to call AsyncSetJobParams() to initialize the asynchronous manager. After this, you can use any of the asynchronous methods! DECLARATION : step : INT := 1 ; file : SysFileAsync.SysFileAsyncFB ; jobparams : SysFileAsync.AsyncJob_Param ; taskName : STRING := 'SysFileAsyncTask' ; // an emtpy string works too but is not self-explanatory open : SysFileAsync.tSysFileOpen ; close : SysFileAsync.tSysFileClose ; ulOut : SysFileAsync.RTS_IEC_HANDLE ; fileName : STRING := 'test.txt' ; State : UDINT ; ASM_Result : SysFileAsync.RTS_IEC_RESULT ; RTS_Result : SysFileAsync.RTS_IEC_RESULT ; iError : INT ; iErrorcode : INT ; // xy means error y in step x xDone : BOOL ; xError : BOOL ; IMPLEMENTATION : CASE step OF 1 : // prepare the FB jobparams.TaskParam.pszTaskname := ADR ( taskName ); // Name of the task. A new task will be created // on first call. If the same name is used // again for other job, task will be re-used jobparams.TaskParam.ulTaskSleepTime := 10 ; jobparams.TaskParam.phTaskHandle := DINT_TO_UDINT ( -1 ); jobparams.TaskParam.ulEndTaskAfterJob := 0 ; file.AsyncSetJobParams ( SysFileAsync.ASYNCJOB_TASK , 1000 , ADR ( jobparams )); step := step + 1 ; 2 : // start open a file asynchronously open.szFile := fileName ; open.am := SysFileAsync.ACCESS_MODE.AM_READ ; open.pulOut := ADR ( ulOut ); open.pResult := ADR ( RTS_Result ); file.SysFileOpenAsync ( ADR ( open ), ADR ( State ), ADR ( ASM_Result )); step := step + 1 ; 3 : // check cyclic if the job is done IF State = SysFileAsync.ASYNCSTATE_READY THEN // the job is done step := step + 1 ; ELSIF State = SysFileAsync.ASYNCSTATE_ERROR THEN // the job failed, check ASM_Result iError := 1 ; ELSIF State = SysFileAsync.ASYNCSTATE_TIMEOUT THEN // the job timed out iError := 2 ; END_IF 4 : // check the RTS results IF ulOut <> SysFileAsync.RTS_INVALID_HANDLE AND RTS_Result = SysFileAsync.Errors.ERR_OK THEN // the file was successfully opened step := step + 1 ; ELSE IF RTS_Result = SysFileAsync.Errors.ERR_NO_OBJECT THEN // The file is not there iError := 1 ; ELSE iError := 2 ; END_IF END_IF 5 : // close the file asynchronously close.pulOut := ADR ( ulOut ); file.SysFileCloseAsync ( ADR ( close ), ADR ( State ), ADR ( ASM_Result )); step := step + 1 ; 6 : // check cyclic if the job is done IF State = SysFileAsync.ASYNCSTATE_READY THEN // the job is done step := step + 1 ; ELSIF State = SysFileAsync.ASYNCSTATE_ERROR THEN // the job failed, check ASM_Result iError := 1 ; ELSIF State = SysFileAsync.ASYNCSTATE_TIMEOUT THEN // the job timed out iError := 2 ; END_IF 7 : // finished without error xDone := TRUE ; 99 : // an error occured, check iErrorcode xError := TRUE ; END_CASE IF iError <> 0 AND NOT xError THEN iErrorcode := step * 10 + iError ; step := 99 ; END_IF Attributes: qualified_only InOut: Scope Name Type Initial Constant iDummyforLibDocuSysFileAsyncMgr INT 99
SysFileAsyncFB (FB) ¶ FUNCTION_BLOCK SysFileAsyncFB EXTENDS AsyncBaseClass Function block to handle file operations asynchronously Methods: SysFileCloseAsync SysFileCopyAsync SysFileDeleteAsync SysFileDeleteByHandleAsync SysFileEOFAsync SysFileGetNameAsync SysFileGetPathAsync SysFileGetPosAsync SysFileGetSizeAsync SysFileGetSizeByHandleAsync SysFileGetStatusAsync SysFileGetTimeAsync SysFileOpenAsync SysFileReadAsync SysFileRenameAsync SysFileSetPosAsync SysFileWriteAsync Structure: SysFileCloseAsync (Method) SysFileCopyAsync (Method) SysFileDeleteAsync (Method) SysFileDeleteByHandleAsync (Method) SysFileEOFAsync (Method) SysFileGetNameAsync (Method) SysFileGetPathAsync (Method) SysFileGetPosAsync (Method) SysFileGetSizeAsync (Method) SysFileGetSizeByHandleAsync (Method) SysFileGetStatusAsync (Method) SysFileGetTimeAsync (Method) SysFileOpenAsync (Method) SysFileReadAsync (Method) SysFileRenameAsync (Method) SysFileSetPosAsync (Method) SysFileWriteAsync (Method)
SysFileAsyncFB.SysFileCloseAsync (METH) ¶ METHOD SysFileCloseAsync : RTS_IEC_HANDLE Method to close a file asynchronous. For details, see node Documentation InOut: Scope Name Type Comment Return SysFileCloseAsync RTS_IEC_HANDLE Input pSysFileClose POINTER TO tSysFileClose Parameter for this operation. See parameter structure for details. pudState POINTER TO UDINT [OUT] Pointer to actual state of the asynchronous job. See ASYNCSTATE_XXX in CmpAsyncMgr.library for details. pResult POINTER TO RTS_IEC_RESULT [OUT] Pointer to the runtime system error code (see CmpErrors2 Interface Library) Result of the asynchronous manager (if asynchronous job is accepted)
SysFileAsyncFB.SysFileCopyAsync (METH) ¶ METHOD SysFileCopyAsync : RTS_IEC_HANDLE Method to copy a file asynchronous. For details, see node Documentation InOut: Scope Name Type Comment Return SysFileCopyAsync RTS_IEC_HANDLE Input pSysFileCopy POINTER TO tSysFileCopy Parameter for this operation. See parameter structure for details. pudState POINTER TO UDINT [OUT] Pointer to actual state of the asynchronous job. See ASYNCSTATE_XXX in CmpAsyncMgr.library for details. pResult POINTER TO RTS_IEC_RESULT [OUT] Pointer to the runtime system error code (see CmpErrors2 Interface Library) Result of the asynchronous manager (if asynchronous job is accepted)
SysFileAsyncFB.SysFileDeleteAsync (METH) ¶ METHOD SysFileDeleteAsync : RTS_IEC_HANDLE Method to delete a file asynchronous. For details, see node Documentation InOut: Scope Name Type Comment Return SysFileDeleteAsync RTS_IEC_HANDLE Input pSysFileDelete POINTER TO tSysFileDelete Parameter for this operation. See parameter structure for details. pudState POINTER TO UDINT [OUT] Pointer to actual state of the asynchronous job. See ASYNCSTATE_XXX in CmpAsyncMgr.library for details. pResult POINTER TO RTS_IEC_RESULT [OUT] Pointer to the runtime system error code (see CmpErrors2 Interface Library) Result of the asynchronous manager (if asynchronous job is accepted)
