This function is used to create a new item at the end of the list defined by the section configured as a parameter, 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.
This function does not write to the data file; consequently, the new item in the section will only be accessible by the functions PgExToolFirstItemSection, PgExToolLastItemSection, PgExToolNextItemSection, PgExToolPreviousItemSection and PgExToolItemSectionInUse if a value is written to the data file beforehand.
Similarly, the PgExToolNewItemSection function will always return the same new item until an entry is written to the data file for the new section.
The PgExToolNewItemSection function does not affect the management of the current list item or the result of the PgExToolItemSectionInUse function.
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 |
Creation successful: ItemSection is configured and contains a section that can be used first in the PgExToolWriteValue function, then in the PgExToolReadValue function, provided one or more values have been written. |
Failure while creating 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. |
-20 |
Non-modifiable ListSection : this control is only performed if the data file is a parameter file for use with an EXIT program. |
Example
/* This example handles a parameter file |
||
/* for use in an EXIT program during a correction validation procedure |
||
ALPHA(256) |
||
PARAM |
||
|
||
/* to manage the list: |
||
ALPHA(40) |
||
ALPHA(50) |
||
NUM_BIN_4 |
||
NUM_BIN_4 |
||
|
||
/* to read and write the value: |
||
ALPHA(40) |
||
ALPHA(200) |
||
NUM_BIN_4 |
||
|
||
/* Beginning of program: loading PgExTool dll |
||
LOAD_DLL 'PgExTool' |
||
/* Updates the report that will be inserted in the |
||
/* final correction validation report |
||
ListSection = 'REPORT_MSG' |
||
SectionSize = 50 |
||
|
||
/* New item section at the end of the report |
||
CALL_DLL 'PgExTool' 'PgExToolNewItemSection' ParamFile ListSection ItemSection SectionSize ReturnCode |
||
Key = 'VALUE' |
||
Value = 'First line of the report' |
||
/* writes the first line of the report |
||
CALL_DLL 'PgExTool' 'PgExToolWriteValue' ParamFile ItemSection Key Value ReturnCode |
||
|
||
/* New item section at the end of the report |
||
CALL_DLL 'PgExTool' 'PgExToolNewItemSection' ParamFile ListSection ItemSection SectionSize ReturnCode |
||
Key = 'VALUE' |
||
Value = *BLANK |
||
/* writes an empty line in the report => carriage return |
||
CALL_DLL 'PgExTool' 'PgExToolWriteValue' ParamFile ItemSection Key Value ReturnCode |
||
/* Note: This write operation normally deletes a key, |
||
/* but in this case, because a new list item is being handled, this action |
||
/* validates the creation of the item section in the data file, |
||
/* even if no keys are written in it. |
||
|
||
/* New item section at the end of the report |
||
CALL_DLL 'PgExTool' 'PgExToolNewItemSection' ParamFile ListSection ItemSection SectionSize ReturnCode |
||
Key = 'VALUE' |
||
Value = 'Third line of the report' |
||
/* writes the last line of the report |
||
CALL_DLL 'PgExTool' 'PgExToolWriteValue' ParamFile ItemSection Key Value ReturnCode |
||
|
||
/* reads the number of lines in the report |
||
Key = 'NB_ITEMS' |
||
ValueSize = 200 |
||
/* reads the number of items in the list section in the parameter file |
||
CALL_DLL 'PgExTool' 'PgExToolReadValue' ParamFile ListSection Key Value ValueSize ReturnCode |
||
/* currently: Value = '3' |
||
/* End of program: unloading PgExTool dll |
||
UNLOAD_DLL 'PgExTool' |
||
Click below for further information about: