|
Description
A transport service user can call the t_optmgmt() function to get, verify or negotiate protocol options with the transport provider.
The fd parameter specifies a transport endpoint. The req and ret parameters each point to an object of type struct t_optmgmt.
The t_optmgmt structure is declared in <xti.h> as follows:
struct t_optmgmt {
struct netbuf opt;
long flags;
};
The opt component specifies the protocol options. The flags component specifies the action to be executed with these options. The options are represented by a netbuf structure, similarly to the addresses with t_bind().
The transport user employs the req parameter to request a specific transport provider with t_optmgmt() and to send options to the transport provider. The user specifies the length of the buffer (in bytes) in which the options are passed to the transport provider, in req->opt.len. req->opt.buf points to this buffer. req->opt.maxlen is meaningless.
Each option is stored in the option buffer req->opt.buf as a t_opthdr structure and must be arranged within the buffer on word boundaries. If the user specifies several options, they must all belong to the same protocol level.
The t_opthdr structure is declared in <xti.h> as follows:
struct t_opthdr {
unsigned long len; /* Defines the total length of the option and */
/* is calculated from the sum of the length */
/* of the t_opthdr structure and the length */
/* of a possible subsequent option value */
unsigned long level; /* Specifies the protocol level */
unsigned long name; /* Specifies the option */
unsigned long status; /* Supplies information as to whether this */
/* option could be set/reset */
};
The user can read from the option buffer and write to it with the OPT_NEXTHDR (pbuf, buflen, poption) macro which is defined in <xti.h>. The pbuf parameter, is a pointer to the start of the option buffer, buflen defines the length of the option buffer and poption is a pointer to the current option within the buffer. The OPT_NEXTHDR macro returns a pointer to the next option or the null pointer if the end of the buffer has been reached.
Before calling t_optmgmt(), the user must specify in ret->opt.maxlen the maximum length (in bytes) of the result buffer in which t_optmgmt() returns this information. req->opt.buf points to this buffer. After t_optmgmt() is executed, ret->opt.len contains the actual length of the returned options and flag values.
The user must specify one of the following actions in req->flags:
T_NEGOTIATE
The user employs this action to negotiate the values of the options specified in req->opt.buf with the transport provider. The transport provider returns the negotiated values in the result buffer ret->opt.buf.
The status field of the relevant t_opthdr structure shows the result of the operation for each option.
The status field can assume the following values:
T_SUCCESS, if the option could be successfully changed.
T_PARTSUCCESS, if an option value lower than the specified one could be set.
T_FAILURE, if the change could not be carried out.
T_READONLY, if the option can only be read and not changed.
T_NOTSUPPORT, if the transport provider does not support the option.
t_optmgmt() returns the lowest common result of all option-specific results in ret->flags. T_NOTSUPPORT has the highest validity and the validity of the results decreases in the order T_NOTSUPPORT, T_READONLY, T_FAILURE, T_PARTSUCCESS, T_SUCCESS.
In each protocol level, the user can reset all options supported in the level concerned to its original values with the T_ALLOPT option. t_optmgmt() then returns all options with their values in the result buffer ret->opt.buf.
T_CHECK
The user can employ this action to check whether the transport provider supports the options specified in req->opt.buf.
If an option is specified without a value, t_optmgmt() only sets the status field in the result buffer ret->opt.buf for this option.
The status field contains one of the following values:
T_SUCCESS, if the transport provider supports the option.
T_NOTSUPPORT, if the transport provider does not support the option.
T_READONLY, if the option is read-only.
If an option is specified with a value, t_optmgmt() returns the result in the manner described above under “T_NEGOTIATE”. t_optmgmt() then returns the lowest common result of all option-specific results in ret->flags.
T_CURRENT
The user can employ this action to get the values of all options specified in req->opt.buf.
After t_optmgmt() is executed, ret->opt.buf contains the options and their current values.ret->opt.flags indicates the result:
T_SUCCESS, if the transport provider supports the option.
T_NOTSUPPORT, if the transport provider does not support the option.
T_READONLY, if the option is read-only.
On each protocol level, the user can employ the T_ALLOPT option to direct t_optmgmt() to return all supported options with their values.
T_DEFAULT
This action allows the user to have the default values of the options specified in *req returned in *ret.
The status field of an option in ret->opt.buf then has the following value:
T_SUCCESS, if the transport provider supports the option.
T_NOTSUPPORT, if the transport provider does not support the option.
T_READONLY, if the option is read-only.
t_optmgmt() then returns the lowest common result of all option-specific results in ret->flags.
On each protocol level, the user can employ the T_ALLOPT option to return all options supported in the level concerned with their original values.
Protocol levels and options
The options are distributed over different protocol levels.
Overview of protocol levels and options:
Protocol level | Option name | Type of option value | Option values |
XTI_GENERIC | XTI_DEBUG | unsigned long | 0 or XTI_GENERIC |
INET_TCP | TCP_KEEPALIVE | struct t_kpalive | (see text) |
TCP_NODELAY | unsigned long | T_YES or T_NO | |
INET_IP | IP_BROADCAST | unsigned int | T_YES or T_NO |
XTI_GENERIC protocol level options
XTI_DEBUG
The user can define whether diagnostic information is to be generated with this option.
XTI_GENERIC specified as an option value: diagnostic information is generated.
No option value specified: no diagnostic information is generated.
See also section "XTI trace" for details of diagnostic information.
INET_TCP protocol level options
TCP_KEEPALIVE
Setting this option activates a mechanism which periodically tests that a connection is still established. The option value is stored in an object of type struct t_kpalive.
The t_kpalive structure is declared in <xti.h> as follows:
struct t_kpalive {
long kp_onoff; /* Enable/disable option */
long kp_timeout; /* Keep-alive timeout in minutes */
};
The “sign-of-life monitoring” for connections can be enabled or disabled with the kp_onoff parameter, which can assume the value T_YES or T_NO.
The kp_timeout parameter is meaningless as the transport system defines the time intervals for connection monitoring itself.
TCP_NODELAY
This option allows the user to influence the time response when sending data.
Data is sent immediately by default. However, if delays occur when sending separate pieces of data, the transport system collects the small amounts of data and sends them together at a later time. This reduces the load on the network. If the TCP_NODELAY option is set (option value T_YES) this mechanism is ineffective, i.e. the data is sent immediately.
INET_IP protocol level options
IP_BROADCAST
The user controls the sending of broadcast messages with this option.
Since broadcast messages can always be sent in BS2000, the IP_BROADCAST option has not functional significance. However, it must be noted that the reception of broadcast messages may be unauthorized.
Return value
0:
If successful.
-1:
If an error occurs. t_ errno is set to indicate the error.
Errors
TACCES
The user has no rights to negotiate the specified options.
TBADF
The specified file descriptor does not reference a transport endpoint.
TBADFLAG
An invalid flag was specified.
TBADOPT
The specified protocol options either had the wrong format or contained invalid information.
TBUFOVFLW
The number of bytes reserved for a result parameter with maxlen are not enough to store the parameter value. The information to be returned in *ret is deleted.
TOUTSTATE
The function was called in the wrong position within a sequence of XTI function calls for transport endpoint fd.
TSYSERR
A system error occurred during execution of this function.