srv_returnval

Defines an output parameter value for a language event.

Important This Open Data Services function or macro is only supported in Microsoft® SQL Server™ version 7.0 for backward compatibility.

For more information about Open Data Services functions or macros supported for backward compatibility, see Open Data Services (Level 3).

Syntax

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

Arguments

srvproc

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

value_name

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

len

Indicates the length, in bytes, of value_name. If value_name 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 data type of the return value to be sent back to the client. The appropriate data type must be specified even if the data is null. For more information about a list of Open Data Services data types, see Data Types.

maxlen

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

datalen

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

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 a 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 a SRV_LANGUAGE event handler when an explicit remote stored procedure call is not involved. In this case, srv_returnval is used to define the data type 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.