Synchronous API Reference

| Introduction | Function Summary | Function Reference |

Function Summary

sync_open Opens up a synchronous connection
sync_getconfig Get settings for the link configuration that is currently active
sync_close Closes a SCALLT
sync_read Receive characters from a synchronous connection
sync_write Send data over a synchronous link
sync_ioctl Sends an ioctl message to the device driver
sync_logmsg Logs message to stdout
sync_setopts Sets global synchronous library options
sync_getopts Gets global synchronous library options
sync_findtag Find a tag in tags list
sync_geterror/sync_geterrno Retrieve most recent library error number
sync_getsyserror Retrieve current library system error number
sync_setuservalue Sets a user supplied value inside SCALLT *
sync_getuservalue Gets a user supplied value inside SCALLT *
sync_setnetent Initializes packetnets file for reading
sync_endnetent Ends packetnets file operations
sync_setfilter Sets packetnets network type filter
sync_getnetent Retrieves next syncnetent structure
sync_getnetbyname Look up packetnets entry by name
sync_getnetbynetid Look up packetnets entry by netid
sync_lookinit Initialize selection mechanism
sync_lookadd Add the SCALLT * to selection list
sync_lookdel sync_lookdel
sync_looksel Checks for readability of SCALLTs
sync_lookclose Close selection list
sync_look Check readability of a single SCALLT *
sync_openstats Open statistics request
sync_closestats Closes statistics request
sync_getstats Obtain statistics
sync_getdevtype Obtain the device name associated with netid
sync_getdevicename Obtain the device name associated with netid
sync_error Prints error message to console
sync_errorstr Copies error message to provided buffer
sync_getfd Returns file descriptor associated with SCALLT *
sync_getdatafd Returns file descriptor associated with SCALLT *
sync_getdevname Return device name associated with SCALLT *
sync_getflags Get flags currently set for SCALLT *
sync_getnetid Return Network ID associated with SCALLT *


| Introduction | Function Summary | Function Reference |

Function Reference


sync_open

Prototypes SCALLT *sync_open(int netid, ...)
SCALLT *sync_opentags(int netid, TAGS *tags)
Purpose Opens up a synchronous connection
Description Open up a synchronous connection.
netid must be valid or this call will fail.
If ST_NETNAME is supplied then the netid argument is ignored.
Suppliying the ST_RAWOPEN, TRUE pair will cause no configuration of the link to take place.
The order of deciding on a configuration set to use is as follows:
  • If ST_RAWOPEN is specified as TRUE then no configuration will be done.
  • If ST_CONFIGFILE is specified then that specified configuration file will be read.
  • Otherwise the CONFIG directive in packetnets will be consulted and the corresponding file opened. This is the configuration set via tsgconfig or the web configurator.
  • If either ST_SPEED or ST_FRAMESIZE are set then those will override the values read from the configuration file.
If ST_TRACE is set to TRUE then this link may be traced. If accessing a remote link then the tracing facility on the remote server may be used otherwise the included tsgtrace utility may be used to trace activity on this link (local tracing only available on Unix).
Tags
  • All global tags
  • ST_NETNAME
  • ST_FLAGS
  • ST_RAWOPEN
  • ST_CONFIGFILE
  • ST_SETFM0
  • ST_FRAMESIZE
  • ST_SPEED
  • ST_TRACE
  • ST_REVDATA
  • ST_USEUDP (Experimental)
Parameters
netid network ID to access
tags pointer to TAGS list
Returns
SCALLT SCALLT * on success
NULL on failure
Errors
  • SYE_BADNETID
  • SYE_SYSERR
  • SYE_BADCONFIG
  • SYE_BADPPA
  • SYE_BADSAP
  • SYE_BADPRIM
  • SYE_UNSUPPORTED
  • SYE_OPENFAIL
  • SYE_TCPBADHOST
  • SYE_CANTCONNECT
  • SYE_TIMEOUT
See Also

| Introduction | Function Summary | Function Reference |


sync_getconfig

Prototypes int sync_getconfig(SCALLT *ct, ...)
int sync_getconfigtags(SCALLT *ct, TAGS *tags)
Purpose Get settings for the link configuration that is currently active
Description Read the settings for the active link configuration.
Some or all of the configuration items for a link may not have been specified using tags passed to sync_open(). Rather, the link configuration items may have come from the link defaults. This function allows the application to determine the configuration for a link. It must be called after sync_open(). The application may, for example, use this function to determine the active framesize so that it can pass an appropriate sized buffer to sync_write().
It is a good idea to check the sync_geterror() return value for more information when a -1 is returned.
Tags
  • ST_SPEED
  • ST_FRAMESIZE
Parameters
ct SCALLT * for the synchronous connection
tags pointer to TAGS list
Returns
0 on success
-1 on failure
Errors
  • SYE_FAILCONFIG
  • SYE_BADSCALLT
See Also

| Introduction | Function Summary | Function Reference |


sync_close

Prototypes void sync_close(SCALLT *ct)
Purpose Closes a SCALLT
Description Closes the file descriptor associated with a specific SCALLT *.
Frees all internally allocated memory.
After this call ct should no longer be considered a valid pointer.
Parameters
ct SCALLT *
See Also

| Introduction | Function Summary | Function Reference |


sync_read

Prototypes int sync_read(SCALLT *ct, ...)
int sync_readtags(SCALLT *ct, TAGS *tags)
Purpose Receive characters from a synchronous connection
Description Receive characters from a synchronous connection.
This function returns the number of bytes read.
The function expects a buffer big enough to hold the largest frame. If the frame is larger than the buffer, this buffer is returned full, and the next sync_read will return the next bytes of the frame. This function returns the number of bytes read or -1 if there was an error.
It is a good idea to check the sync_geterror() return value for more information when a -1 is returned. If blocking is set (the default) then this function will attempt to read without error ST_MAXTRIES (default 20) times and will wait 1 second after each failed attempt.
Tags
  • All global tags
  • ST_BUFFER
  • ST_BUFLEN
  • ST_MAXTRIES
  • ST_BLOCK
  • ST_TIMEP
Parameters
ct SCALLT * to receive from
tags pointer to TAGS list
Returns
number of characters read on success
0 if nothing could be read with ST_BLOCK 0
-1 on failure
Errors
  • SYE_BADSCALLT
  • SYE_BADBUFFER
  • SYE_SYSERR
See Also

| Introduction | Function Summary | Function Reference |


sync_write

Prototypes int sync_write(SCALLT *ct, ...)
int sync_writetags(SCALLT *ct, TAGS *tags)
Purpose Send data over a synchronous link
Description Send data over a synchronous link.
The data appears "as is" except that the driver will prepend a flag character and append a 16 bit CRC to the data. This function returns the number of bytes written or -1 if a failure occurs. In the event of a failure use sync_geterror() to determine the cause. When unable to write data due to flow control, this function will sleep one second after receiving a time-out and then try again for ST_MAXTRIES (default 20) times.
Tags
  • All global tags
  • ST_BUFFER
  • ST_BUFLEN
  • ST_MAXTRIES
  • ST_BLOCK
Parameters
ct SCALLT * to send on
tags pointer to TAGS list
Returns
number of bytes written on success
0 if nothing could be written given ST_BLOCK=FALSE
-1 on failure
Errors
  • SYE_BADSCALLT
  • SYE_BADBUFFER
  • SYE_SYSERR
  • SYE_UNDELIVERED
See Also

| Introduction | Function Summary | Function Reference |


sync_ioctl

Prototypes int sync_ioctl(SCALLT *ct, int cmd, char *buf, int len, int timeout)
Purpose Sends an ioctl message to the device driver
Description Sends an ioctl message down the streams stack associated with ct.
Parameters
ct pointer to SCALLT
cmd ioctl type
buf ioctl buffer
len length of buffer
timeout timeout for ioctl
Returns
0 on success
-1 on failure
Errors
  • SYE_BADSCALLT
  • SYE_SYSERR

| Introduction | Function Summary | Function Reference |


sync_logmsg

Prototypes void sync_logmsg(char *s, ...)
Purpose Logs message to stdout
Description Logs messages to the console (stdout).
Parameters
s printf style string

| Introduction | Function Summary | Function Reference |


sync_setopts

Prototypes int sync_setoptstags(SCALLT *ct, TAGS *tags)
int sync_setopts(SCALLT *ct, ...)
Purpose Sets global synchronous library options
Description Sets global Synchronous library parameters.
Any function using tags arguments will call this function.
Tags
  • All global tags
  • ST_VERBOSE
  • ST_BLOCK
  • ST_OUTERR
  • ST_LOGFILE
  • ST_TIMEOUT
  • ST_SETCRC
  • ST_SETRTS
  • ST_SETDTR
Parameters
ct SCALLT *
tags pointer to TAGS list
Returns
0 on success
-1 on failure
See Also

| Introduction | Function Summary | Function Reference |


sync_getopts

Prototypes int sync_getoptstags(SCALLT *ct, TAGS *tags)
int sync_getopts(SCALLT *ct, ...)
Purpose Gets global synchronous library options
Description Obtains the value of global Synchronous library parameters or parameters associated with a specific connection.
Tags
  • All global tags
  • ST_VERBOSE
  • ST_BLOCK
  • ST_OUTERR
  • ST_LOGFILE
  • ST_TIMEOUT
  • ST_GETDSR
  • ST_GETCTS
  • ST_GETDCD
Parameters
ct SCALLT *
tags pointer to TAGS list
Returns
0 on success
-1 on failure
See Also

| Introduction | Function Summary | Function Reference |


sync_findtag

Prototypes int sync_findtag(TAGS *tags, unsigned long item)
Purpose Find a tag in tags list
Description Finds the tag item in the tags array pointed to by tags.
Parameters
tags pointer to TAGS list
item item to find in tags
Returns
>= 0 Index of the item
-1 Item not found

| Introduction | Function Summary | Function Reference |


sync_geterror/sync_geterrno

Prototypes int sync_geterror(void)
int sync_geterrno(void)
Purpose Retrieve most recent library error number
Description Retrieves most recent library error code from the library.
If the return value is SYE_SYSERR, a call to sync_getsyserror() will retrieve the system error defined in errno.h.
See Also

| Introduction | Function Summary | Function Reference |


sync_getsyserror

Prototypes int sync_getsyserrno(void)
Purpose Retrieve current library system error number
Description Retrieves current library system error number if sync_geterror() returned SYE_SYSERR.
See Also

| Introduction | Function Summary | Function Reference |


sync_setuservalue

Prototypes void sync_setuservalue(SCALLT *ct, unsigned long val)
Purpose Sets a user supplied value inside SCALLT *
Description Sets a 32bit value inside SCALLT * which can be retrieved at any later time using sync_getuservalue.
See Also

| Introduction | Function Summary | Function Reference |


sync_getuservalue

Prototypes unsigned long sync_getuservalue(SCALLT *ct)
Purpose Gets a user supplied value inside SCALLT *
Description Sets a 32bit value inside SCALLT * which can be retrieved at any later time using sync_getuservalue.
See Also

| Introduction | Function Summary | Function Reference |


sync_setnetent

Prototypes void sync_setnetent(void)
Purpose Initializes packetnets file for reading
Description Allocates resources necessary to read the configuration database (packetnets database). This is only required for sync_getnetent(), but not for other sync_getnetby... functions. After sync_getnetent() returns NULL, a call to sync_endnetent() is required to release the resources.
See Also

| Introduction | Function Summary | Function Reference |


sync_endnetent

Prototypes void sync_endnetent(void)
Purpose Ends packetnets file operations
Description Ends packetnets file operations.
See Also

| Introduction | Function Summary | Function Reference |


sync_setfilter

Prototypes void sync_setfilter(int typemask)
Purpose Sets packetnets network type filter
Description Sets a network type filter for all accesses to the packetnets file so that the functions sync_getnetent(), sync_getnetby...() will return only the specified network types. Default type is NETSYNC_TYPE. After using the net functions, it is usually a good idea to reset the filter to defaults.
The typemask is a type of network ie. NETX25_TYPE, NETFREL_TYPE, etc. may be OR'd together or NETALL_TYPE selecting all protocol/card types except disabled network IDs.
If typemask is set to 0 or -1 we reset to the default type (NETSYNC_TYPE).
Parameters
typemask type of network
See Also

| Introduction | Function Summary | Function Reference |


sync_getnetent

Prototypes syncnetent *sync_getnetent(void)
Purpose Retrieves next syncnetent structure
Description Retrieves next syncnetent entry from the packetnets file.
This function only returns synchronous (NETSYNC_TYPE) entries by default. See sync_setfilter() to change.
Returns
syncnetent * structure containing information about this network
NULL on failure
See Also

| Introduction | Function Summary | Function Reference |


sync_getnetbyname

Prototypes syncnetent *sync_getnetbyname(char *name)
Purpose Look up packetnets entry by name
Description Attempts to look up a network entry given a name.
This function only returns synchronous (NETSYNC_TYPE) entries by default. See sync_setfilter() to change.
Parameters
name name of network in packetnets
Returns
syncnetent * structure containing information about this network
NULL on failure
See Also

| Introduction | Function Summary | Function Reference |


sync_getnetbynetid

Prototypes syncnetent *sync_getnetbynetid(int netid)
Purpose Look up packetnets entry by netid
Description Attempts to look up a network entry given a netid.
This function only returns synchronous (NETSYNC_TYPE) entries by default. See sync_setfilter() to change.
Parameters
netid netid of network in packetnets
Returns
syncnetent * structure containing information about this network
NULL on failure
See Also

| Introduction | Function Summary | Function Reference |


sync_lookinit

Prototypes sync_lookent *sync_lookinit(int maxnetids)
Purpose Initialize selection mechanism
Description Initializes the selection mechanism for file descriptors. Currently the limit for the number of file descriptors to listen on is 256. If maxnetids is specfied to be more than 256 the call will succeed, but still only 256 file descriptors are allowed. The pointer returned by this function must be used in all the other "sync_look" functions expecting a sync_lookent.
Parameters
maxnetids maximum number of netids
Returns
look sync_lookent * - on success
NULL on failure
See Also

| Introduction | Function Summary | Function Reference |


sync_lookadd

Prototypes int sync_lookadd(sync_lookent *look, SCALLT *ct)
Purpose Add the SCALLT * to selection list
Description Add the file descriptor associated with ct to the selection list contained in look.
Parameters
look sync_lookent pointer
ct SCALLT *
Returns
0 on success
-1 on failure
See Also

| Introduction | Function Summary | Function Reference |


sync_lookdel

Prototypes int sync_lookdel(sync_lookent *look, SCALLT *ct)
Purpose sync_lookdel
Description Remove the file descriptor associated with ct from the selection list contained in look.
Parameters
look sync_lookent pointer
ct SCALLT *
Returns
0 on success
-1 on failure
See Also

| Introduction | Function Summary | Function Reference |


sync_looksel

Prototypes SCALLT *sync_looksel(sync_lookent *look, int tmout)
Purpose Checks for readability of SCALLTs
Description Checks for availability of frames for the SCALLTs in the selection list created through sync_lookadd()s.
Parameters
look sync_lookent pointer
tmout timeout: -1 block indefinitely, 0 do not block
Returns
ct SCALLT * if a frame is readable on that SCALLT *
NULL noting is readable or timeout has occured
See Also

| Introduction | Function Summary | Function Reference |


sync_lookclose

Prototypes void sync_lookclose(sync_lookent *look)
Purpose Close selection list
Description Closes the selection mechanism for look.
Parameters
look sync_lookent pointer
See Also

| Introduction | Function Summary | Function Reference |


sync_look

Prototypes int sync_look(SCALLT *ct, int tmout)
Purpose Check readability of a single SCALLT *
Description Checks for availability of a frame to be read for the netid associated with ct.
Parameters
ct SCALLT *
tmout timeout: -1 block indefinitely, 0 do not block
Returns
1 if there is a frame to be read
0 nothing to read or timeout
-1 on failure
See Also

| Introduction | Function Summary | Function Reference |


sync_openstats

Prototypes int sync_openstats(int netid, int type)
Purpose Open statistics request
Description Open statistics request of type "type" on given Network ID.
Only one type of statistics request may be made at a time.
Parameters
netid network ID
type only SYNC_BOARDSTATS
Returns
0 on success
-1 on failure: type is not SYNC_BOARDSTATS
-2 on failure: can't open device
See Also

| Introduction | Function Summary | Function Reference |


sync_closestats

Prototypes void sync_closestats(void)
Purpose Closes statistics request
Description Close statistics request.
See Also

| Introduction | Function Summary | Function Reference |


sync_getstats

Prototypes int sync_getstats(int netid, char *buf, int len)
Purpose Obtain statistics
Description Obtain statistics of the type declared in sync_openstats into an adequately sized buffer buf of length len.
Example 

    #include "libsynctcp.h"
    #include "brdstats.h"
    WANlinkstats linkstats;
    int netid = 0;
    if (sync_open(netid, SYNC_BOARDSTATS) == 0)
    {
        if (sync_getstats(netid, (char *) &linkstats, sizeof(linkstats)) == 0)
        {
    	// statistics gathered
    	printf("Transmitted %d frames.\n", linkstats.tx_frames);
        }
        sync_closestats();
    }
Parameters
netid network ID
buf buffer which is to contain stats
len length of buffer which is to contain stats
Returns
0 on success
-1 on failure
See Also

| Introduction | Function Summary | Function Reference |


sync_getdevtype

Prototypes int sync_getdevtype(int netid)
Purpose Obtain the device name associated with netid
Description Get the device type of the physical device for the Network identified by netid.
Parameters
netid network ID
Returns
id device ID
0 if not found
See Also

| Introduction | Function Summary | Function Reference |


sync_getdevicename

Prototypes int sync_getdevicename(int netid, char *name)
Purpose Obtain the device name associated with netid
Description Get the device name of physical device for the Network identified by netid.
Parameters
netid network ID
name string to hold name of device or NULL
Returns
id device ID
0 if not found
See Also

| Introduction | Function Summary | Function Reference |


sync_error

Prototypes void sync_error(char *errstring)
Purpose Prints error message to console
Description Writes the error message associated with a Synchronous library error to stdout.
Also prints out the error string associated with a system error (in errno.) (not under SV4 & Windows NT)
SV4 only: the errno value is appended to the error string.
Windows NT only: the value returned by GetLastError() is appended to the error string.
Use of stdout is restricted to Console (Text mode) applications.
Parameters
errstring string to prepend to output
See Also

| Introduction | Function Summary | Function Reference |


sync_errorstr

Prototypes int sync_errorstr(char *buf, int buflen)
Purpose Copies error message to provided buffer
Description Copies the error message associated with the most recent Synchronous library error into buf.
Parameters
buf pointer to a string to hold the error message
buflen length of provided buf
Returns
0 on success
-1 on failure
See Also

| Introduction | Function Summary | Function Reference |


sync_getfd

Prototypes int sync_getfd(SCALLT *ct)
Purpose Returns file descriptor associated with SCALLT *
Description Returns control message file descriptor associated with SCALLT *.
Parameters
ct SCALLT *
Returns
fd file descriptor
-1 on failure
See Also

| Introduction | Function Summary | Function Reference |


sync_getdatafd

Prototypes int sync_getdatafd(SCALLT *ct)
Purpose Returns file descriptor associated with SCALLT *
Description Returns file descriptor for data messages associated with SCALLT *.
Parameters
ct SCALLT *
Returns
fd data file descriptor
-1 on failure
See Also

| Introduction | Function Summary | Function Reference |


sync_getdevname

Prototypes char *sync_getdevname(SCALLT *ct)
Purpose Return device name associated with SCALLT *
Description Returns the device name associated with SCALLT. For Synchronous over TCP this returns "TCP".
Parameters
ct SCALLT *
Returns
char * name of device
NULL on failure

| Introduction | Function Summary | Function Reference |


sync_getflags

Prototypes int sync_getflags(SCALLT *ct
Purpose Get flags currently set for SCALLT *
Description Get flags currently set for SCALLT *.
Parameters
ct SCALLT *
Returns
flags flags
-1 on failure

| Introduction | Function Summary | Function Reference |


sync_getnetid

Prototypes int sync_getnetid(SCALLT *ct)
Purpose Return Network ID associated with SCALLT *
Description Returns Network ID associated with SCALLT * as provided to sync_open().
Parameters
ct SCALLT *
Returns
netid Network ID
-1 on failure

| Introduction | Function Summary | Function Reference |



Wed Oct 13 15:18:03 2004 by xtractxml.pl$Revision: 1.2 $
Copyright (C) 2003 The Software Group Limited. All Rights Reserved.