This socloc API module has the file name sconnect.c. This callable API will parse or build a socloc connect string. In addition, this API also includes a function to translate sconnect return code to an English phrase. This API module does not contain any socket calls. This API module contains only public functions. Note that there is no DOS or QNX version of this API.
Here is a list of functions in this module:
This module is part of the socloc API and needs to be linked with the following modules:
In the Linux or Unix platform, this module is compiled along with the other socloc modules as part of the script csocloc. A good example of a shell script for a client application that uses this API is mksockc.
This module depends on the following header files:
Prototype : int sconnect_parse(char *com, int sflag, char *sname, char *hname, int *port, char *ip) Parameters : Name : comm Description : connect string Name : sflag Description : service name allowed flag Name : sname Description : returned service name Name : hname Description : returned host name Name : port Description : returned TCP port number Name : ip Description : returned IP address Returns : sconnect code
This function will attempt to parse a connect string into its component parts. The flag sflag controls whether the service name is allowed as part of the connect string (0=no, 1=yes). At least one parameter pair is expected in the connect string (com). All pointer parameters are expected to be not null except for ip. If the service name is not allowed, a null sname pointer is allowed. Upon successful completion, the components of the connect string will be loaded into the returned values. The returned values which are string pointers must point to an already allocated string large enough to hold the returned value.
Prototype : int sconnect_build(char *sname, char *hname, int *port, char *ip, char *scout) Parameters : Name : sname Description : service name Name : hname Description : host name Name : port Description : TCP port number Name : ip Description : IP address Name : scout Description : returned connect string Returns : sconnect code
This function will attempt to build a connect string from the component parts. The parameter scout is required to be not null and already allocated to sufficient size for the returned sconnect string. All other parameters may be a null pointer. At least one parameter (other than scout) must be present. Any parameter that contains a value will be used to form the sconnect string.
Prototype : void sp_code_string(int ret, char *mes) Parameters : Name : ret Description : sconnect code Name : mes Description : returned English phrase
This function will translate an sconnect code to an English phrase. All parameters are required. The parameter mes is also required to be already allocated to sufficient size for the returned string.
All sconnect functions return a code called a sconnect code which is a zero or positive integer. sconnect codes are defined in the header sconnect.h. Notice that all sconnect code definitions start with:
Your application must check the return code of each sconnect function call. If the result is not:
you must take some action.