6.48 LceReceiveNextX
Retrieves the selected record which is being sent immediately from the host.
|
BOOL |
LceReceiveNextX |
(int |
iSession, |
|
|
|
char * |
strBuffer, |
|
|
|
BUFLEN |
bufferSize, |
|
|
|
PFIELD_DETAILS |
pDataDetails, |
|
|
|
int |
iFields) |
Parameters
|
iSession |
The session identifier. |
|
strBuffer |
A pointer to a buffer to contain the returned record. |
|
iBufferSize |
The size of the buffer passed. |
|
pDataDetails |
For each field, it provides the length of the data and any special flags. See the structure definition in the LCOE.H header file. Refer to notes for further details. |
|
iFields |
The maximum number of fields to retrieve in the buffer. |
Return Values
TRUE is returned if the session can receive the selected record.
FALSE is returned if no more records are found or an error occurs. To distinguish between an error and no record found, use the LceGetStatus function to check that no error exists.
Notes
The LceReceiveNextX function is used with a number of select processing functions but only after a call to LceRequestSelect or LceRequestSelectWhere and if you are using the *RECEIVEIMMED option.
The general pattern of these functions is as follows:
- LceSetSelectOptions with option *RECEIVEIMMED specified.
- LceRequestSelect or LceRequestSelectWhere selects records on the host. (The LceRequestSelectWhere function allows you to attach a Where clause to your selection criteria.)
- LceReceiveNextX reads the records transferred from the host to the PC. (Unless you have another session open, once a *RECEIVEIMMED select has been initiated, then all the records must be selected via the LceReceiveNextX function before any other function which results in communication with the Host (e.g. LceFetch) can be performed.
If at any time the remaining records for a Select call are not needed, they can be discarded by executing an LceDeleteSelect function.
If no buffer is specified, when a call to LceReceiveNextX is performed, all the values in the field information will be updated with the values for the current record. These values can be obtained in the same way you would retrieve the field values after a call to LceGetSelect, i.e. using the LceGetFieldValueX function.
If a buffer is specified, the buffer will be updated with the field values in the order specified on the call to LceRequestSelect. This buffer is for use in your client program and it cannot be accessed by other LANSA Open functions, i.e. LceGetFieldValueX/LceGetFieldValueU. The buffer provides a more efficient method of accessing the data. Using the buffer can improve performance greatly.
The size of each value returned is stored in fieldLen in the pDataDetails parameter. You can use fieldLen to move from field to field in the buffer. This size includes the 0x00 terminator between the values.
ulFlags in the pDataDetails parameter identifies the returned value as *SQLNULL. If the field has a value of *SQLNULL, pulFlags will return 1 otherwise it will return 0.
To ensure the buffer is large enough to store the data for all requested fields, use the maximum field length when determining the amount of memory to allocate for the buffer. This can be obtained using LceGetFieldType. However, the maximum may not always be required. Since RDMLX fields are not padded, a smaller buffer may be sufficient. An error will be displayed if the buffer is not large enough to store all the requested fields.
For backward compatibility the size of each value returned for an RDML field will continue to be defined by the following rules:
|
ALPHA |
FIELD LENGTH+1 |
|
SIGNED |
FIELD LENGTH+4 |
|
PACKED |
FIELD LENGTH+4 |
This size includes the 0x00 terminator between the values. If the value is actually shorter than the length specified then it will be padded with 0x00. This padding occurs after processing the current setting for alpha or numeric pad/strip.
- This function may only be executed once a session has been opened.
Related Functions