srv_returnval

Defines an output parameter value for a language event.

Syntax

int srv_returnval (
SRV_PROC * srvproc,
DBCHAR * valuename,
int len,
BYTE status,
DBINT type,
DBINT maxlen,
DBINT datalen,
BYTE * value );

where

srvproc

Is a pointer to the SRV_PROC structure that is the handle for a particular client connection. The structure contains the information that the ODS Library uses to manage communication and data between the Open Data Services server application and the client.

valuename

Is the name of the return value. It can be NULL, since a return value is not required to have a name.

len

Indicates the length, in bytes, of valuename. If valuename is null-terminated, set len to SRV_NULLTERM.

status

Specifies the status of the return value. Currently, there is only one legal status, SRV_PARAMRETURN.

type

Specifies the datatype of the return value to be sent back to the client. The appropriate datatype must be specified even if the data is NULL. For a list of Open Data Services datatypes, see Datatypes.

maxlen

Indicates the maximum length of the value, in bytes. For fixed-length datatypes that don't allow null values (for example, srvint4 or srvmoney), maxlen is ignored. For fixed-length datatypes that allow null values (for example, srvintn or srvmoneyn), maxlen must be the size of the datatype when it is not NULL. For variable-length datatypes, maxlen is the maximum length that the datatype can be.

datalen

Indicates the actual length, in bytes, of value. This parameter is ignored for fixed-length datatypes.

If datalen is 0, then a null value is returned.

value

Is a pointer to the program variable that contains the return value. The return value data is copied into the private srvproc space when srv_returnval is called. The return value data is sent when srv_senddone is called.

Returns

SUCCEED or FAIL.

Remarks

Usually, output parameters are returned by an SRV_RPC event handler and are handled with the srv_paramset function. However, it is possible for an Open Data Services server application to return values from an SRV_LANGUAGE event handler when an explicit remote stored procedure call is not involved. In this case, srv_returnval is used to define the datatype and value of the return value.

Multiple output parameter values can be sent to a client in a set of results, but srv_returnval must be called once for each parameter. The return values are sent back automatically when srv_senddone is called. The output parameters are sent back in the order in which they were defined with srv_returnval.

To send a null value, set datalen to 0.

When srv_returnval is called, the data at location value is copied into the SRV_PROC private data space. This copying makes it safe to use value later for other purposes.

See Also