Sensoray 2600 - Manual (Page 21)

Sensoray 2600 Programming Guide
17
Gateway Transaction Control
Chapter 6: Gateway Transaction Control
6.1 Overview
The functions in this section are used to initialize and execute gateway transactions.
6.2 Transaction Control Functions
6.2.1 S26_SchedOpen()
Function: Begins a new gateway transaction.
Prototype: void *S26_SchedOpen( u32 hbd, u32 retries );
Returns: Handle to a new gateway transaction, or zero if the transaction could not be created.
Notes: S26_SchedOpen() starts the construction of a new gateway transaction. The new transaction will be empty (i.e., it
will have no scheduled IOM actions). After successfully calling this function, IOM actions can be scheduled into
the transaction, and when all desired actions have been scheduled, the transaction may be executed.
Except for GWERR_MMCLOSED , all transaction errors are negated in the new transaction. The GWERR_MMCLOSED error
will be asserted if the target MM is closed when the transaction is created. If the MM is open, GWERR_MMCLOSED
will be negated and it will be possible to schedule actions into and execute the transaction.
Important: To prevent resource leaks and other potential problems, S26_SchedExecute() or
S26_SchedExecuteFinish() must be called for each transaction that is successfully started by
S26_SchedOpen() . This must be done even if gateway errors were generated while scheduling IOM actions into
the transaction and the errors are detected before the transaction is executed. There is no need, however, to call
either
S26_SchedExecute() or S26_SchedExecuteFinish() if S26_SchedOpen() fails to create a new
transaction, although there is no harm in doing so.
Example: See the example in section 6.2.2.
6.2.2 S26_SchedExecute()
Function: Executes a transaction.
Prototype: u32 S26_SchedExecute( XACT x, u32 msec, u8 *IomStatus );
Returns: Error code as described in section 5.5. Zero is returned if the operation was successful.
Notes: S26_SchedExecute() sends the transaction’s gateway command packet to the MM and waits for the MM to reply
with a gateway response packet. The calling thread is blocked until either a response packet is received or the
Parameter Type Description
hbd u32 MM handle.
retries u32 Maximum number of transaction retry attempts.
Parameter Type Description
x void * Transaction handle obtained from S26_SchedOpen().
msec u32 Maximum time to wait for the gateway response packet, in milliseconds, before
declaring a time-out.
IomStatus u8 * Pointer to a 16-byte buffer that will receive the status bytes from all IOMs. Set to zero
if you are not interested in receiving IOM status info.