ADS-sum command: Read or Write a list of variables with one single ADS-command

Background :

ADS offers powerful and fast communication to exchange any kind of information. It's possible to read single variables or complete arrays and structures with each one single ADS-API call.
This new ADS command offers to read with one singale ADS call multiple variables which are not structured within a linear memory.

As a result the ADS caller application (like scada Systems etc.) can extremly speed up cyclic polling :
Sample :

• Until now : Polling 4000 single variables which are not in a linear area (like array / structure / fixed PLC address ) would cause 4000 single Ads-ReadReq with each 1-2 ms protocol time.
  As a result the scanning of these variables take 4000ms-8000ms.
• New Ads-Command allows to read multiple variables with one single ADS-ReadReq : 4000 single variables are handled with e.g. 8 single Ads-ReadReq (each call requesting 500 variables) with each 1-2 ms protocol time.
  As a result the scanning of these variables take just few 10ms.
  

Requirements and important limitations:

Note that ADS is just a transport layer, but there could be important side effects. So read these requirements and take care on limitations:

• Version of target ADS Device:
  ADS itself is just the transport layer, but the requested ADS device has to support the ADS-Command.
• Bytes length of requested data:
  Requesting a large list of values from variables is fine, but the requested data of the Ads-response (the data-byte-length) have to pass the AMS-router (size by default a 2048kb)
  So the caller has to limit the requested variables based on calculation of requested data-byte-length.
• Number of Sub-ADS calls: Highly recommended to max. 500!
  If the PLC is processing one ADS request, it will completely work on this single ADS request BEFORE starting next PLC cycle.
  As a result one single ADS request with 200.000 sub-Ads-requests would cause that PLC would collect and copy 200.000 variables into one single ADS response, before starting next PLC.
  So this large number of ads-sub-commands will jitter the PLC execution!

Notice We highly recommend to not request more than 500 Ads-Sub commands.

// This code snippet using ADSIGRP_SUMUP_READ with IndexGroup 0xF080 and IndexOffset as number of ADS-sub-commands 
// Demonstrates how to read a list of variables, see full demo-code

// Use ADS-ReadWrite request : "Write" the requested data down to ADS device and "Read" the received answer 

 nErr = AdsSyncReadWriteReq( pAddr, 
                0xF080,         // Sum-Command, response will contain ADS-error code for each ADS-Sub-command
                reqNum,     // number of ADS-Sub-Commands
                4*reqNum+reqSize, // number requested bytes in the sample two variables each 4 bytes. NOTE : we request additional "error"-flag(long) for each ADS-sub commands
                (void*)(mAdsSumBufferRes), // provide buffer for response 
                12*reqNum, // send 12 bytes for each variable (each ads-Sub command consist of 3 * ULONG : IG, IO, Len)
                &parReq);

// This code snippet using ADSIGRP_SUMUP_WRITE with IndexGroup 0xF081 and IndexOffset as number of ADS-sub-commands 
// Demonstrates how to write a list of variables, see full demo-code

// Use ADS-ReadWrite request : "Write" the send a list of data to list of variables down to ADS device and "Read" the received return codes

 nErr = AdsSyncReadWriteReq( pAddr, 
                0xF081,     // ADS list-write command
                reqNum,     // number of ADS-Sub commands
                4*reqNum,     // we expect an ADS-error-return-code (long) for each ADS-Sub command
                (void*)(mAdsSumBufferRes), // provide space for the response containing the return codes
                16*reqNum, // cbyteLen : in THIS sample we send two variables each 4 byte
                        // --> send 16 bytes (IG1, IO1, Len1, IG2, IO2, Len2, Data1, Data2) 
                &parReq); // buffer with data