SysDirAsync (LIB)

Version: 3.5.17.0
Author: 3S - Smart Software Solutions GmbH
Placeholder: SysDirAsnc

Description 1 

All asynchronous system libraries are only asynchronous wrappers around their underlaying System-Library. So this library is only an asynchronous wrapper around the SysDir.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:

t<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;
    dir : SysDirAsync.SysDirAsyncFB;
    jobparams : SysDirAsync.AsyncJob_Param;
    taskName : STRING := 'SysDirAsyncTask'; // an emtpy string works too but is not self-explanatory
    open : SysDirAsync.tSysDirOpen;
    read : SysDirAsync.tSysDirRead;
    close : SysDirAsync.tSysDirClose;
    hDir : SysDirAsync.RTS_IEC_HANDLE;
    dirName: STRING := ''; // an emtpy string represents the working directory
    stateJob : UDINT;
    ASM_Result: SysDirAsync.RTS_IEC_RESULT;
    RTS_Result: SysDirAsync.RTS_IEC_RESULT;
    dirInfo : SysDirAsync.dirInfo;
    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 := TO_UDINT(-1);
        jobparams.TaskParam.ulEndTaskAfterJob := 0;

        dir.AsyncSetJobParams(SysDirAsync.ASYNCJOB_TASK, 1000000, ADR(jobparams));
        step := step + 1;

        2: // start open a directory asynchronously
        open.szDir := dirName;
        open.diMaxDirEntry := 80;
        open.pDirInfo := ADR(dirInfo);
        open.pulOut := ADR(hDir);
        open.pResult := ADR(RTS_Result);

        dir.SysDirOpenAsync(ADR(open), ADR(stateJob), ADR(ASM_Result));
        step := step + 1;

        3: // check cyclic if the job is done
        IF stateJob = SysDirAsync.ASYNCSTATE_READY THEN
            // the job is done
            step := step + 1;
        ELSIF  stateJob = SysDirAsync.ASYNCSTATE_ERROR THEN
            // the job failed, check ASM_Result
            iError := 1;
        ELSIF  stateJob = SysDirAsync.ASYNCSTATE_TIMEOUT THEN
            // the job timed out
            iError := 2;
        END_IF

        4: // check the RTS results
        IF hDir <> SysDirAsync.RTS_INVALID_HANDLE AND RTS_Result = SysDirAsync.Errors.ERR_OK THEN
            // the dir was successfully opened
            step := step + 1;
        ELSE
            IF RTS_Result = SysDirAsync.Errors.ERR_PARAMETER THEN
                // The dir is not there
                iError := 1;
            ELSIF RTS_Result = SysDirAsync.Errors.ERR_END_OF_OBJECT THEN
                // The dir is empty
                iError := 2;
            ELSE
                iError := 3;
            END_IF
        END_IF

        5: // read next dir entry
        read.diMaxDirEntry := 80;
        read.pDirInfo := ADR(dirInfo);
        read.pulOut := ADR(RTS_Result);
        dir.SysDirReadAsync(ADR(read), ADR(stateJob), ADR(ASM_Result));
        step := step + 1;

        6: // check cyclic if the job is done
        IF stateJob = SysDirAsync.ASYNCSTATE_READY THEN
            // the job is done
            step := step + 1;
        ELSIF  stateJob = SysDirAsync.ASYNCSTATE_ERROR THEN
            // the job failed, check ASM_Result
            iError := 1;
        ELSIF  stateJob = SysDirAsync.ASYNCSTATE_TIMEOUT THEN
            // the job timed out
            iError := 2;
        END_IF

        7: // check the RTS results
        IF RTS_Result = SysDirAsync.Errors.ERR_OK THEN
            // the dir entry was successfully read, read next
            step := 5;
        ELSIF RTS_Result = SysDirAsync.Errors.ERR_END_OF_OBJECT THEN
            // There are no more dir entries to read
            step := step + 1;
        ELSE
            // An error occured, close the directory any way
            step := step + 1;
        END_IF

        8: // close the dir asynchronously
        close.pulOut := ADR(hDir);

        dir.SysDirCloseAsync(ADR(close), ADR(stateJob), ADR(ASM_Result));
        step := step + 1;

        9: // check cyclic if the job is done
        IF stateJob = SysDirAsync.ASYNCSTATE_READY THEN
            // the job is done
            step := step + 1;
        ELSIF stateJob = SysDirAsync.ASYNCSTATE_ERROR THEN
            // the job failed, check ASM_Result
            iError := 1;
        ELSIF  stateJob = SysDirAsync.ASYNCSTATE_TIMEOUT THEN
            // the job timed out
            iError := 2;
        END_IF

        10: // 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

Contents:

Indices and tables

1: Based on SysDirAsync.library, last modified 20.04.2021, 16:02:32. LibDoc 3.5.16.40

The content file SysDirAsync.library.json was generated with CODESYS V3.5 SP16 Patch 3 on 20.04.2021, 16:02:32.

SysDirAsync (LIB)

Description 1

USAGE of the FB:

Contents:

Indices and tables

Description 1 