Socloc Parse/Build Connect String API

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.

Goto Top | Socloc Overview | Future Lab Home | Contact Webmaster | Feedback

Copyright © 2000-2006 Future Lab, Last Updated Jun 30, 2006