This function locates the section matching the next item in the list defined by the section configured as a parameter, and retrieves it into the data file.
Important: The PgExTool dll must be loaded (using the LOAD_DLL instruction) at the beginning of the program and must still be loaded when section list management functions are called.
Parameters
ALPHA(256) |
File |
Full name of the data file. |
ALPHA(n) |
ListSection |
List section. |
ALPHA(n) |
ItemSection |
List item section (updated by the function) in the ListSection#number form; ItemSection should be specified to contain more than ListSection . |
NUM_BIN_4 |
SectionSize |
Size of ItemSection : n. |
NUM_BIN_4 |
ReturnCode |
Read return code (updated by the function). |
Possible return code values
0 |
Read operation successful: ItemSection is configured, and contains a section that can be used in the functions PgExToolReadValue and PgExToolWriteValue. |
Failure while retrieving the list item: ItemSection is cleared.
-1 |
Parameter file not found. |
-2 |
Invalid ListSection : - either ListSection is empty, - or the data file is a parameter file for use with an EXIT program and ListSection is not one of the permitted sections. |
-4 |
ItemSection is too small to contain the result of the function. |
-10 |
The requested list item does not exist: - either the previous position in the list was the last list item, meaning there is no next item. In this case, the PgExToolItemSectionInUse function returns the final item in the list. - or else no position in the list section has yet been set; consequently, the system cannot position to the next item. |
Example
/* This example runs through a list in a parameter file |
||
/* for use in an EXIT program during a correction validation procedure |
||
ALPHA(256) |
||
PARAM |
||
|
||
ALPHA(40) |
||
ALPHA(50) |
||
NUM_BIN_4 |
||
NUM_BIN_4 |
||
|
||
ALPHA(40) |
||
ALPHA(200) |
||
|
||
/* Beginning of program: loading PgExTool dll |
||
LOAD_DLL 'PgExTool' |
||
/* Runs through the list of objects received during the correction validation |
||
|
||
ListSection = 'RECEIVED_OBJECT' |
||
SectionSize = 50 |
||
|
||
/* reads the first item section in the list |
||
CALL_DLL 'PgExTool' 'PgExToolFirstItemSection' ParamFile ListSection ItemSection SectionSize ReturnCode |
||
|
||
DO_WHILE ReturnCode = 0 |
||
/* the parameters associated with the received object can then be read |
||
/* using ItemSection; for example the name of the received object: |
||
Key = 'NAME' |
||
ValueSize = 200 |
||
CALL_DLL 'PgExTool' 'PgExToolReadValue' ParamFile ItemSection Key Value ValueSize ReturnCode |
||
|
||
|
||
/* reads the next item section (next object received) |
||
CALL_DLL 'PgExTool' 'PgExToolNextItemSection' ParamFile ListSection ItemSection SectionSize ReturnCode |
||
REDO |
||
/* End of program: unloading PgExTool dll |
||
UNLOAD_DLL 'PgExTool' |
||
Click below for further information about: