3.1.4 JSMX_BINDLST
The JSMX_BINDLST API is optional and is used to "bind" a list to the specified connection handle so that the list entries can be sent or received by the subsequent JSMX_COMMAND API call.
Only one list may be bound at once – you must issue the JSMX_BINDLST call before the JSMX_COMMAND call(s) that uses it.
The JSMX_BINDLST call is not persistent – that is, it lasts only until the next JSMX_COMMAND call completes.
You must call JSMX_BINDLST again before a subsequent JSMX_COMMAND API call, if the service command requires a bound list. (The same is true for bound fields – see the JSMX_BINDFLD.)
To "unbind" a list from the specified connection handler, you can pass a null value (use *OMIT in RPG) for the JSMMETA or JSMLIST parameters or pass a zero value for the JSMMETASIZE or JSMLISTSIZE parameters.
The JSMX_BINDLST API operates independently of the JSMX_BINDFLD API – that is you may bind a set of non-recurring fields (using JSMX_BINDFLD), a list (using JSMX_BINDLST) or both.
Whether you need to use one, both or neither will depend on the function and requirements of the service and service command you are using.
Parameters
|
No.
|
Symbolic Name
|
Description
|
|
1
|
JSMHDL
|
Input, character 4.
The JSMX_OPEN call returns the connection handle it assigns to this connection. This handle is used on subsequent JSMX_COMMAND and other API calls to identify the connection to which the call applies.
|
|
2
|
JSMMETA
|
Input, structure.
Specifies a block of memory that contains zero or more field meta-data definitions corresponding to the structure of the fields in each entry of the list provided in JSMLIST.
Each meta-data entry must be formatted as follows: Positions Description
1 – 50 Symbolic field name (50)
This name does not have to be the same as the name used in the RPG program. However, for some LANSA Integrator services the symbolic name must match that expected by the service – this is particularly so for those services such as the XML and SOAP services that perform mapping between external data and program fields.
51 Data Type (1)
Supported types are A, P or S.
52 – 58 Field size (7)
This is the number of characters or digit positions, not the byte size.
59 – 60 Field decimal places (2).
|
|
3
|
JSMMETASIZE
|
Input, integer 10.
Specifies the size of the memory block provided in the JSMMETA parameter in bytes. This must be a multiple of 60 (60 being the size of a single meta-data entry).
|
|
4
|
JSMLIST
|
Input/Output, structure.
Specifies a block of memory that contains the list described by the JSMMETA parameter.
Depending upon the service and the service command, the list entres might be used as input to the service, output from the service or both. When used as output from the service, the JSM will write the output entries to the memory identified by this parameter.
In an RPG program, the list is usually implemented as a multiple occurrence data structure.
|
|
5
|
JSMENTRYSIZE
|
Input, integer 10.
Specifies the size of each list entry. This should normally be equal to the sum of the byte sizes of the fields described by the JSMMETA parameter.
|
|
6
|
JSMENTRYCOUNT
|
Input/Output, integer 10.
On entry, this specifies the number of entries provided by the client application in the list identified by the JSMLIST parameter. If the client application does not provide list entries for the service command, then the application should specify zero.
Upon return, if the service command normally writes entries to the list provided, then it will update this field with the number of entries written (up to the maximum specified by the JSMENTRYMAX parameter).
|
|
7
|
JSMENTRYMAX
|
Input, integer 10.
Specifies the maximum number of list entries that can be held in the list specified by the JSMLIST parameter.
|
|
8
|
JSMSTS
|
Output, character (variable, recommended 20).
The JSM server returns the status of the operation in this field. The client application can test this field to determine whether the operation succeeded. In most cases a status of 'OK' indicates successful completion.
|
|
9
|
JSMMSG
|
Output, character (variable, recommend 512).
The JSM server may return a message concerning the operation in this field - for example a completion message or an error message when the operation fails. Some service commands may return data related to the service in this field.
|
|
