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

sync_close

| 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

sync_open

| 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

sync_open

| 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

sync_write

| 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

sync_read

| 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

sync_getopts

| 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

sync_getopts

| 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	sync_getsyserror sync_error sync_errorstr
\| 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	sync_geterror sync_error sync_errorstr
\| 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	sync_getuservalue
\| 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	sync_setuservalue
\| 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	sync_endnetent sync_getnetent sync_getnetbynetid sync_getnetbyname sync_setfilter
\| Introduction \| Function Summary \| Function Reference \|

sync_endnetent
Prototypes	`void sync_endnetent(void)`
Purpose	Ends packetnets file operations
Description	Ends packetnets file operations.
See Also	sync_setnetent sync_getnetent sync_getnetbynetid sync_getnetbyname sync_setfilter
\| 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

sync_setnetent
sync_endnetent
sync_getnetent
sync_getnetbynetid
sync_getnetbyname

| 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

sync_setnetent
sync_endnetent
sync_getnetbynetid
sync_getnetbyname
sync_setfilter

| 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

sync_setnetent
sync_endnetent
sync_getnetent
sync_getnetbynetid
sync_setfilter

| 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

sync_setnetent
sync_endnetent
sync_getnetent
sync_getnetbyname
sync_setfilter

| 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

sync_lookadd
sync_lookdel
sync_looksel
sync_lookclose

| 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

sync_lookinit
sync_lookdel
sync_looksel
sync_lookclose

| 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

sync_lookinit
sync_lookadd
sync_looksel
sync_lookclose

| 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

sync_lookinit
sync_lookadd
sync_lookdel
sync_lookclose

| 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

sync_lookinit
sync_lookadd
sync_lookdel
sync_looksel

| 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

sync_looksel

| 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

sync_getstats
sync_closetats

| Introduction | Function Summary | Function Reference |

sync_closestats
Prototypes	`void sync_closestats(void)`
Purpose	Closes statistics request
Description	Close statistics request.
See Also	sync_openstats sync_getstats sync_closetats
\| 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

sync_openstats
sync_getstats
sync_closetats

| 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

sync_getdevicename
sync_getdevname

| 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

sync_getdevname
sync_getdevtype

| 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

sync_errorstr

| 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

sync_error

| 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

sync_getdatafd

| 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

sync_getfd

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

Synchronous API Reference

Function Summary

Function Reference

sync_open

sync_getconfig

sync_close

sync_read

sync_write

sync_ioctl

sync_logmsg

sync_setopts

sync_getopts

sync_findtag

sync_geterror/sync_geterrno

sync_getsyserror

sync_setuservalue

sync_getuservalue

sync_setnetent

sync_endnetent

sync_setfilter

sync_getnetent

sync_getnetbyname

sync_getnetbynetid

sync_lookinit

sync_lookadd

sync_lookdel

sync_looksel

sync_lookclose

sync_look

sync_openstats

sync_closestats

sync_getstats

sync_getdevtype

sync_getdevicename

sync_error

sync_errorstr

sync_getfd

sync_getdatafd

sync_getdevname

sync_getflags

sync_getnetid