3.3.3 JSMX_BINDFLD

The JSMX_BINDFLD API is optional and is used to "bind" fields to the specified connection handle so that the field values can be sent or received by a subsequent JSMX_COMMAND API call.

Only one set of fields may be bound at once – therefore you should include all required fields and their descriptions in a single JSMX_BINDFLD call before the JSMX_COMAND call(s) in which they might be used.

The JSMX_BINDFLD call is not persistent – that is, it lasts only until the next JSMX_COMMAND call completes.

You must call JSMX_BINDFLD again before a subsequent JSMX_COMMAND API call, if the service command requires bound fields.  (The same is true for bound lists – see the JSMX_BINDLST.)

To "unbind" fields from the specified connection handle, you can pass a null value (use *OMIT in ILE RPG) for the JSMMETA or JSMDATA parameters or pass a zero value for the JSMMETASIZE or JSMDATASIZE parameters.

The JSMX_BINDFLD API operates independently of the JSMX_BINDLST 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

Number

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 provided in JSMDATA.  You must provide one field meta-data definition for each field in the structure provided in JSMDATA, and in the same order as the fields occur in JSMDATA.

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 – 58Field 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

JSMDATA

Input/Output, structure.

Specifies a block of memory that contains the fields described by the JSMMETA parameter.

Depending upon the service and the service command, the field values 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 field values to the memory identified by this parameter.

5

JSMDATASIZE

Input, integer 10.

Specifies the size of the memory block provided in the JSMDATA parameter in bytes.  This should normally be equal to the sum of the byte sizes of the fields described by the JSMMETA parameter.

6

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.

7

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.