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:

• sconnect_parse
• sconnect_build
• sp_code_string

Module Dependencies

This module is part of the socloc API and needs to be linked with the following modules:

• fio.c
• parse.c
• logger.c
• ipcomm.c
• sloc.c
• sliocode.c
• slconfig.c

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.

Module Header Files

This module depends on the following header files:

• stdhead.h
• flsocket.h
• sconnect.h

Module Functions

sconnect_parse

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.

sconnect_build

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.

sp_code_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.

Sconnect Codes

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:

   SP_

Your application must check the return code of each sconnect function call. If the result is not:

   SP_OK

you must take some action.