Functions

See Cross System Communication for more usage and full examples.

Working with the ATN core

atninit( )

Initializes the ATN core, and connects to an array of STRINGs where console messages get dumped. This function should be called before any other ATN functions.

atncyclic( )

Optional interface to the ATN core for processing cyclic console commands. Must be called cyclically.

The intended use is to pass in a ‘command’ via the buffer, and ATN will output text to the array of STRINGs that were passed in to the atninit function. Think of it like a command line interface to ATN. The simplest command that can be input is ?, and this results in output of the following form in the Console array:

Reading Status

Reading a combined boolean state

Set of functions that return a boolean if any/all registered Active bits are true/false

stateAllTrue( )

returns true if ALL the registered active bits are true.

stateAllFalse( )

returns true if ALL the registered active bits are false.

stateAnyTrue( )

returns true if ANY the registered active bits are true.

stateAnyFalse( )

returns true if ANY the registered active bits are false.

isInhibited( )

this is a special case of the stateAnyTrue function, and behaves the same way. It has been renamed to improve readability with the inhibit model.

Reading overall state status

Set of functions that populate an array of STRINGs with the status that each module has registered for a particular state in the system. If the state STRING is passed in as “CoolerState”, for example, and there are (3) modules that have registered a status bit to that state, then calling one of the functions below will populate an array of STRINGs with (3) entries, one for each of the registered modules.

stateStatus( )

The STRING array has an entry for every module that registered with this state. Each entry indicates the module name, and the current value of the state (active or inactive). Example string entry: “inactive - Module A”.

stateFalseStatus( )

The STRING array only has entries for registered modules whose state value is currently FALSE. Each entry contains the name of the module alone.

stateTrueStatus( )

The STRING array only has entries for registered modules whose state value is currently TRUE. Each entry contains the name of the module alone.

Reading individual states

Set of iterator functions that return each status that is registered to a state

stateCount( )

Get the number of statuses registered to a state

forState( )

Function to populate the local structure with the state of each item registered to a state. This function is preferred for read only statuses. The user passes in a pointer to a local structure for the function to populate.

The size of the structure is compared to the size of the registered structure before a copy is done. More detailed type checking is up to the user.

Example

Using `forState`` to read and consolidate a number of pending alarm counts

    //Reset the local count
	AlarmCount := 0;

    //For loop through the items. Its ok that this is off by one, 
    //  because the forState will return false for invalid items
    //  NOTE: In STRUCTURED TEXT If you do a stateCount() - 1 then with ZERO items, 
    //      it will count backwards.
	FOR item := 0 TO stateCount(gAlarmApi.PendingAlarms) DO

        //Copy the remote data to the local structure if it matches
		IF forState( gAlarmApi.PendingAlarms, item, 0, ADR(count), SIZEOF(count)) THEN

            //Add to the count
			AlarmCount := 	AlarmCount + count;

		END_IF

	END_FOR	

forStateGetPointer( )

Function to get a pointer to the parameter structure of each item registered to a state. This function is required if the parameters must be written to. The user passes in a pointer to a pointer of user defined type (UserType **) for the function to populate.

The size of the structure is output for the user to check before dereferencing. More detailed type checking is up to the user.

Example

Using forStateGetPointer to read and consolidate a number of pending alarm counts and reset the local counts

    //Reset the local count
	AlarmCount := 0;

    //For loop through the items. Its ok that this is off by one, 
    //  because the forState will return false for invalid items
    //  NOTE: In STRUCTURED TEXT If you do a stateCount() - 1 then with ZERO items, 
    //      it will count backwards.
	FOR item := 0 TO stateCount(gAlarmApi.PendingAlarms) DO

        //Get a pointer to the remote data
		IF forStateGetPointer( gAlarmApi.PendingAlarms, item, 0, ADR(pCount), ADR(sCount)) THEN
            
            //Validate the pointer by checking the size matches
            IF countSize = SIZEOF(sCount) THEN

                //Access the remote data
                dCount ACCESS pCount;

                //count the data
    			AlarmCount := 	AlarmCount + dCount;
                
                //Set the remote variable
                 dCount := 0;

            END_IF
		END_IF

	END_FOR	

Setting Commands

executeCommand( )

Function that sets the command bool for all items registered to a given command

AtnPLCOpen( )

Function Block to execute commands and get feedback from registered systems.

This will set the subscribed bools to true, then check the registered [AtnPlcOpenStatus] from the modules. It will set the plcopen status to ERR_FUB_BUSY on the modules, then check for when they are ERR_OK. Modules returning statuses other than ERR_OK or ERR_FUB_BUSY are considered error’d modules, and the function block will report error and stop checking.

No other action is taken. If follow up action needs to be done, the user must implement this.

AtnPLCOpenWithParameters( )

Function Block to execute commands with parameters and get feedback from registered systems.

This will set the subscribed bools to true, then check the registered atnPLCOpenStatus_typ from the modules. It will set the plcopen status to ERR_FUB_BUSY on the modules, then check for when they are ERR_OK. Modules returning statuses other than ERR_OK or ERR_FUB_BUSY are considered error’d modules, and the function block will report error and stop checking.

No other action is taken. If follow up action needs to be done, the user must implement this.

Subscribing to commands

Simple command

subscribeCommandBool( )

Function to subscribe a boolean that should be set to true when the given command is executed

PLCOpen command/status

subscribePLCOpen( )

Function to subscribe a boolean that should be set to true when the given command is executed, along with a PLCOpen status to check.

subscribePLCOpenWithParameters( )

Function to subscribe a boolean that should be set to true when the given command is executed, along with a PLCOpen status to check. It also accepts parameters.

Registering Status

Simple status

registerStateBool( )

Function to register a boolean status bit to the Active bit of a specific state. Automatically gets the address of the bool in Structured Text.

registerStateBoolAdr( )

Function to registers a boolean status bit to the Active bit of a specific state. Required to register Function block OUTPUT bits as they are readonly.

Complex status

registerStateParameters( )

Function to register parameters to a state.

registerStateExt1( )

Function to register parameters to a state with full api support.

Working with shared resources

registerToResource( )

Function to request exclusive access to a shared resource.

resourceIsAvailable( )

Function to check if a resource is available. If this function returns TRUE, it means that no other module has requested access to this resource, and that it is available for the calling module to request access to. Note that this function will return TRUE even if the resource is being actively requested by the calling module.

Diagnostics

systemJson( )

This function dumps a log of all registered states to a STRING in JSON format.