Rockwell Automation 1789-L10_L30_L60 SoftLogix 5800 System User Manual - Manual (Page 120)

120 Rockwell Automation Publication 1789-UM002J-EN-P - December 2012
Chapter 7 Develop External Routines
The control structure for an external routine contains control, status, and meta
information for that routine. The control structure is accurate at the time of its
invocation and it enables the external routine to validate and influence its
operation. Upon routine completion, the control structure contains status about
the routine’s execution as to its degree of success or failure. Other data areas are
either reserved or defined by you.
The meta information includes the definitions of the parameters passed to the
external routine (paramDefs) and the parameter that is returned from the routine
(returnDef ). The meta information is read-only. It is derived at download time
and then set upon every call to its corresponding external routine. These
definitions let the external routine determine if it is being used in the proper
context. The routine can check this information, which includes a parameter’s
type, the number of elements in the event of an array, and the number of bits in
each of these elements.
The remaining meta information exists in the ctrlWord: the number of
parameters (numParams), whether a return value (ReturnsValue) is expected by
the caller, and whether it’s executing during Normal, Pre, or Post scan (ScanType).
All the meta information is set by the system and the external routine developer
should treat it as read-only. Any modifications to this information is disregarded.
Control and status information exist in one location inside the
RoutineControlWord structure (ctrlWord) within the external routine control.
Control information consists of EnableIn and FirstScan. This information is set
upon every invocation of the external routine. EnableIn reflects the rung status at
the time of the call. FirstScan indicates whether this is the first scan after
switching the controller to Run mode. Use EnableIn to enable operation of the
external routine and use FirstScan, or possibly Prescan, to perform any necessary
initialization in the external routine.
Status information is set by the external routine. The Enable (EN), Done (DN),
and Error (ER) bits are used much like other ladder control structures. Set the
EN bit when the external routine is enabled. Set the DN bit when the operation
is complete. If an error occurs during execution, set the ER bit and store an error
code in the ErrorCode member.
Another piece of status information is EnableOut. Set this bit if the external
routine is used to compute rung status and the result indicates a TRUE
condition. The system does not however update system rung status based on this
information. It is used as an indication to the caller.
The controller does not modify or initialize the user defined bits (User). The use
of these bits is up to the external routine developer.
// Fixed size structure defining JXR's signature and control.
struct EXT_ROUTINE_CONTROL
// 4 + 120 + 12 = 136 bytes long
{
RoutineControlWord ctrlWord;
EXT_ROUTINE_PARAMETERS paramDefs[MAX_PARAMS];
EXT_ROUTINE_PARAMETERS returnDef;
};