Synchronous Library API Programmer's Guide

Introduction

The Synchronous library allows a program to write synchronous data directly to a synchronous line. The hardware adds only start and end flags, zero bit insertion and a 16 bit CRC. All protocol headers are the responsibility of the user program. Outgoing frames are formed with the data buffer of each sync_write call (see example below).

The library is based on a concept called Tags, which it uses to obtain parameters for some functions. Tags should always be passed in pairs: the tag itself and its value. (An exception to this is the last tag, which must ALWAYS be TAG_END!)

An Example:

     SCALLT *scallt;
     int rc, netid = 0;
     char *buf = "Hello World";

     scallt = sync_open(netid, TAG_END);
     rc = sync_write(scallt,
                         ST_BUFFER, buf,
                         ST_BUFLEN, sizeof(buf),
                         TAG_END);
    sync_close(scallt);
 

Any function capable of accepting tag arguments can be called in either of two ways. The first is to pass a variable number of tag arguments This method allows for great flexibility, especially the ability to use C's conditional operator to create conditional tags. Example:

SCALLT scallt;
char buf0[2048];
char buf1[2048];
int buflen = 2048;
int currentbuf;
int rc;
rc = sync_read(scallt, currentbuf == 0 ? ST_BUFFER : ST_IGNORE, &buf0[0],
		  currentbuf == 1 ? ST_BUFFER : ST_IGNORE, &buf1[0],
		  ST_BUFLEN, buflen,
		  TAG_END);

SCALLT scallt;
char buf[2048];
TAGS mytags[] = { {ST_BUFFER, &buf[0]}, {ST_BUFLEN, 30}, {TAG_END, 0} };
int rc;
rc = sync_read(scallt, mytags);

Most functions will return 0 for success or -1 for failure.

Error handling is done by looking at the return of sync_geterror() or sync_error(). sync_errorstr() may be called to translate the error code into words.

[ NT vs 95 | Functions | Contents | Tags | Errors ]

NT / 95 Comparison

The outline of the Synchronous library is identical for both NT and 95 applications. A typical application will use the 5 basic functions, sync_open(), sync_read(), sync_write(), sync_look(), and sync_close() to perform the data transfer. However, Windows 95 does not support the numerous utility routines that are used under Windows NT. See Function list showing routines supported by 95 and NT. See Error list showing error codes specific to 95.

Netid - NT vs 95

An application communicates with a specific adapter and port by supplying a Netid in the sync open() function. The determination of the Netid varies between NT and 95. Under NT the function sync_getnetbyname() can be used to obtain the Netid based on a known link name. Under 95 the Netid is computed using the formula Netid = (board# * 4) + link#, where board# and link# are values between 0 and 3. Under NT the Netid can also be computed but the computation is more complex because the number of links each adapter supports is used in the equation.

For example, a machine with one 2 port adapter and one 4 port adapter would have the following Netid values depending on the order of the adapters.

Compilation

A properly designed application will require little to no coding changes to run on both NT and 95. To generate a single binary that runs on both platforms it is necessary to note the following:

[ Functions | Contents | Tags | Errors

Synchronous Library Functions

The following routines are contained within the Synchronous library. All functions are supported under Windows NT. A subset of functions are supported under Windows 95, these functions have been identified below with ⁹⁵ following the function name.

General Functions

sync_open ⁹⁵

Open sync connection

sync_close ⁹⁵

Close sync connection

sync_read ⁹⁵

Read data

sync_write ⁹⁵

Write data

Frame Reception Status Functions

Overview

Overview of Frame Reception Status Functions

sync_look ⁹⁵

Check for frames

sync_lookinit

Initialize the selection list

sync_looksel

Check for data on multiple links

sync_lookadd

Add an SCALLT to the selection list

sync_lookdel

Remove an SCALLT from the selection list

sync_lookclose

Close/Free the selection list

Network Lookup Functions

Overview

Overview of Network Lookup Functions

sync_setnetent

Start Network file lookup operations

sync_endnetent

Stop Network file lookup operations

sync_getnetent

Get Network entry

sync_getnetbyname

Lookup Network by Name

sync_getnetbynetid

Lookup Network by Network ID

sync_setfilter

Set the Network type filter

Error Handling Functions

sync_error

Print Error Information

sync_errorstr ⁹⁵

Copy Error Information into buffer

sync_geterror ⁹⁵

Obtain error code

sync_getsyserror

Obtain system error code

Adapter Statistics Functions

sync_openstats

Open device for Stats Request

sync_closestats

Close device for Stats Request

sync_getstats

Obtain Statistics

Miscellaneous Functions

sync_logmsg

Log Message to a file or stderr

sync_setopts ⁹⁵

Set Global Tags

sync_getopts

Obtain Global Tags

sync_findtag

Find Tag given Tag list

sync_getdevtype

Obtain Physical device type and name

sync_getdevicename

Obtain Physical device type and the device string.

sync_setuservalue

Set the value associated with a SCALLT

sync_getuservalue

Get the value associated with a SCALLT

Macros (SCALLT *ct)

SYNC_FD(ct)

file descriptor for SCALLT

SYNC_DEVNAME(ct)

device name for this call

SYNC_NETID(ct)

Network ID for this call

SYNC_ISINIT(ct)

Is the SCALLT structure initialized?

[ NT vs 95 | Functions | Contents | Tags | Errors ]

Example Program

/***********************************************************************
 *  Module Name: libtest.c
 *
 *  Description:
 *   Sends a string NUMTIMES times over a synchronous link
 ***********************************************************************/
 
#include <stdio.h>
#include "libsync.h"

#define NUMTIMES        100
 
main(int argc, char **argv)
{
    SCALLT *ct;
    char errbuf[256];
    int i, netid = 0;
    char *buf = "This is the string being sent across the synchronous link";

    if (argc > 1)
        netid = atoi(argv[1]);
    /*
     * Prior to any sync activity, obtain a handle for operating
     * the link.
     */
    if (!(ct = sync_open(netid, TAG_END)))
    {
        sync_errorstr(errbuf, sizeof(errbuf));
	printf ("Error: sync_open: %s\n", errbuf);
        exit(1);
    }
    /*
     * Send the same string to the remote machine NUMTIMES times
     */
    for (i = 0; i < NUMTIMES; i ++)
    {
        if (sync_write(ct, ST_BUFFER, buf,
                        ST_BUFLEN, strlen(buf),
                        TAG_END) < 0)
        {
            sync_errorstr(errbuf, sizeof(errbuf));
	    printf ("Error: sync_write: %s\n", errbuf);
            break;
        }
    }
    /*
     * Now we're done. Close and exit.
     */
    sync_close(ct);
    exit(0);
}

[ NT vs 95 | Functions | Contents | Tags | Errors ]

Synchronous Library Error Codes

The following is a list of error codes which sync_geterror() can return. These errors codes are supported by NT and 95. If the error is set to SYE_SYSERR check errno for more details. sync_error() will write out both Synchronous Library errors and system errors to stdout. Writing to stdout is only supported by Console (Text mode) Applications. sync_errorstr() will write the error into a user supplied buffer.

SYE_BADNETID

Bad Network ID

SYE_BADBUFFER

Zero Length or Null Pointer specified

SYE_UNDELIVERED

Transmitter failure, data undelivered

SYE_FAILCONFIG

Link Configuration Failed. Invalid config file or invalid netid

Error Codes Specific to Windows NT

SYE_SYSERR

System Error Message

SYE_FILEFMT

Internal Error: Bad File Format of Packetnets file

SYE_NOTFOUND

Internal Error: Packetnets file not found

SYE_BADERRMSG

Internal Error: Unknown Error Message From Protocol Driver

SYE_OUTSTATE

Internal Error: Protocol Driver Received Message Out of State

SYE_BADPRIM

Bad Primitive

SYE_NOCONFIG

Configuration File Not Found

SYE_OPENFAIL

Open of Device Failed

SYE_BADPPA

Bad PPA (Physical Point of Attachment)

SYE_BADSCALLT

Bad SCALLT Structure

SYE_BADCONFIG

Bad Configuration file

SYE_UNSUPPORTED

Internal Error: Service known but not supported

Error Codes Specific to Windows 95

SYE_VXDTHREADDIED

sync_open failed because the thread controlling the VxD has died

SYE_MEMORYALLOC

sync_open failed due to memory allocation failure

SYE_CREATESEM

sync_open failed due to Semaphore Creation failure

SYE_CREATEEVT

sync_open failed due to Event Creation failure

SYE_OPENVXD

sync_open failed due to CreateFile of VxD failure

SYE_CREATETHREAD

sync_open failed due to Creation of VxD failure

SYE_MEM_CONFLICT

sync_open failed due to adapter memory conflict. Another device is using the memory space requested by the adapter.

SYE_INCOMPATIBLE_DLL

sync_open failed due to dll and VxD are not compatible. A partial or unsuccessful upgrade of the synchronous software has made the adapter unusable. Remove the synchronous software and re-install.

SYE_PORT_INUSE

sync_open failed due to this board/link combination already in use

SYE_IRQ_NOT_AVAILABLE

sync_open failed due to IRQ is invalid, or inuse by another device

SYE_IO_NOT_AVAILABLE

sync_open failed due to adapter IO is inuse by another adapter

SYE_MEMBASE_NOT_AVAILABLE

sync_open failed due to adapter memory is inuse by another adapter

SYE_NUMPORT_BAD

sync_open failed due to IO memory conflict, incorrect OEM pals, or adapter not installed

SYE_OEM_INVALID

sync_open failed due to incorrect OEM pal installed or adapter not installed

SYE_TOO_MANY_ADAPTERS

sync_open failed due to the number of adapters exceeding the maximum of 4.

SYE_INVALID_SERNO

sync_open failed due to invalid serial number or activation key

SYE_TIMEOUT

sync_read or sync_write failed due to timeout

SYE_BUFFERTOOSMALL

sync_read failed due to buffer size too small. Retry with a buffer as large as the frame size. No data has been discarded.

SYE_QUEUEFULL

sync_write failed because transmit queue is full. The transmit queue size is contained in the link configuration.

[ NT vs 95 | Functions | Contents | Tags | Errors ]

Synchronous Library Tags

This is a list of currently supported tags and an explanation of their meaning.

Special Tags:

TAG_END

Signifies end of Tag List

TAG_DONE

Synonym for TAG_END

TAG_IGNORE

Ignore this tag and it's value

Global tags:

ST_VERBOSE

Comment on progress to stdout on Console Applications

ST_BLOCK

Blocking call?

Not Supported Under Windows NT!

ST_OUTERR

FILE *ptr for error messages

Not Supported Under Windows NT!

ST_LOGFILE

Log file to use (defaults to stderr)

Not Supported Under Windows NT!

Function Specific Tags:

ST_NETNAME

Network Name

ST_BUFFER

Pointer to Buffer

ST_BUFLEN

Size of Buffer

ST_FLAGS

Flags to pass to open()

ST_SETCRC

Set CRC generation on/off (Boolean) (only on Sync/570 board)

ST_SETDTR

Set state of DTR signal (Boolean).

ST_SETRTS

Set state of RTS signal (Boolean).

ST_GETDSR

Get state of DSR signal (Boolean).

ST_GETCTS

Get state of CTS signal (Boolean).

ST_GETDCD

Get state of DCD signal (Boolean).

[ NT vs 95 | Functions | Contents | Tags | Errors ]

General Functions

sync_open

Supported OS:

Windows NT

Windows 95

Function Prototype:

SCALLT *sync_open(int netid, TAG LIST);

SCALLT *sync_opentags(int netid, TAGS *tags)

Description:

Open up a synchronous connection.
netid must be valid or this call will fail.

Tags recognized:

ST_NETNAME

ST_FLAGS

all tags recognized by sync_setopts

Arguments:

netid - Network ID to access

TAG LIST - tag pair list ending with TAG_END

tags - pointer to array of TAGS and values, terminated by TAG_END

Returns:

A pointer to a SCALLT structure - on success

NULL - on failure

Possible Errors:

SYE_BADNETID

SYE_SYSERR

SYE_BADCONFIG ^NT

SYE_BADPPA ^NT

SYE_VXDTHREADDIED ⁹⁵

SYE_MEMORYALLOC ⁹⁵

SYE_CREATESEM ⁹⁵

SYE_CREATEEVT ⁹⁵

SYE_OPENVXD ⁹⁵

SYE_CREATETHREAD ⁹⁵

SYE_MEM_CONFLICT ⁹⁵

SYE_INCOMPATIBLE_DLL ⁹⁵

SYE_PORT_INUSE ⁹⁵

SYE_IRQ_NOT_AVAILABLE ⁹⁵

SYE_IO_NOT_AVAILABLE ⁹⁵

SYE_MEMBASE_NOT_AVAILABLE ⁹⁵

SYE_NUMPORT_BAD ⁹⁵

SYE_OEM_INVALID ⁹⁵

SYE_TOO_MANY_ADAPTERS ⁹⁵

SYE_INVALID_SERNO ⁹⁵

See Also:

sync_close

sync_setopts

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_close

Supported OS:

Windows NT

Windows 95

Function Prototype:

void sync_close(SCALLT *ct)

Description:

Closes the file descriptor and frees internally allocated memory associated with a specific Netid.
After this call ct should no longer be considered a valid pointer.

Note:

Under Windows 95 this function must be called for all open CALLTs before the application terminates. Otherwise, resources are not guaranteed to be released and subsequent Netid use maybe denied until the PC is rebooted.

Arguments:

ct - pointer to SCALLT structure

Returns:

None

See Also:

sync_open

sync_setopts

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_read

Supported OS:

Windows NT

Windows 95

Function Prototype:

int sync_read(SCALLT *ct, TAG LIST);

int sync_readtags(SCALLT *ct, TAGS *tags)

Description:

Receive characters from a synchronous connection.
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 for more information when a -1 is returned.
Windows NT:
The function will attempt to read without error ST_MAXTRIES (default 20) times and will wait 1 second after each failed attempt. The function will always block so it may be desirable to determine if there is anything to read before blocking. The sync_look function will accomplish this.
Windows 95:
This function will wait one second for ST_MAXTRIES times (default 4). When no data is available for reading, this function will sleep one second after receiving a timeout and then try again for ST_MAXTRIES times. Setting ST_MAXTRIES to 0 will cause the read not to block.

Tags recognized:

ST_BUFFER

ST_BUFLEN

ST_MAXTRIES

all tags recognized by sync_setopts

Arguments:

ct - pointer to SCALLT structure

TAG LIST - tag pair list ending with TAG_END

tags - pointer to array of TAGS and values, terminated by TAG_END

Returns:

number of characters read - on success

-1 - on failure

Possible Errors:

SYE_BADBUFFER

SYE_SYSERR

SYE_TIMEOUT ⁹⁵

SYE_VXDTHREADDIED ⁹⁵

SYE_BUFFERTOOSMALL ⁹⁵

See Also:

sync_write

sync_setopts

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_write

Supported OS:

Windows NT

Windows 95

Function Prototype:

int sync_write(SCALLT *ct, TAG LIST)

int sync_writetags(SCALLT *ct, TAGS *tags);

Description:

Send data over an established synchronous connection.
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 timeout and then try again for ST_MAXTRIES (default 20 on Windows NT, 4 on Windows 95) times. Setting ST_MAXTRIES to 0 will cause the write not to block. On NT the function will return SYE_SYSERR if a timeout occurs.

Tags recognized:

ST_BUFFER

ST_BUFLEN

ST_MAXTRIES

all tags recognized by sync_setopts

Arguments:

ct - pointer to SCALLT structure

TAG LIST - tag pair list ending with TAG_END

tags - pointer to array of TAGS and values, terminated by TAG_END

Returns:

Number of bytes written - on success

-1 on failure

Possible Errors:

SYE_BADBUFFER

SYE_SYSERR

SYE_UNDELIVERED ^NT

SYE_TIMEOUT ⁹⁵

SYE_VXDTHREADDIED ⁹⁵

SYE_QUEUEFULL ⁹⁵

See Also:

sync_read

sync_setopts

[ NT vs 95 | Functions | Contents | Tags | Errors ]

Overview of Frame Reception Status Functions

If only one circuit is to be monitored, then using sync_look is the simplest method. However, this approach does not easily scale when 2 or more circuits require monitoring.

The recommended method for multi-circuit applications is to use the sync_lookxxxx series of functions. This set of functions is used to manipulate and monitor a list of circuits. sync_lookinit initializes the list, sync_lookadd and sync_lookdel manipulate list entries, sync_looksel queries the list for available data packets and sync_lookclose frees the list.

sync_look

Supported OS:

Windows NT

Windows 95

Function Prototype:

int sync_look(SCALLT *ct, int tmout);

Description:

Checks for availability of a frame to be read for the netid associated with ct.

Arguments:

ct - pointer to SCALLT structure

tmout - millisecs to wait (use -1 for infinity, 0 for no wait)

Returns:

1 - if there is a frame to be read

0 - nothing to read

See Also:

sync_looksel

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_lookinit

Supported OS:

Windows NT

Function Prototype:

sync_lookent *sync_lookinit(int maxnetids);

Description:

Initializes the selection mechanism for file descriptors. Currently the limit for the number of file descriptors to listen on is imposed by the maximum number of boards (4) multiplied by the maximum number of links per board (4). Thus 16 is the maximum value for maxnetids. The pointer returned by this function must be used in all the other "look" functions expecting a sync_lookent.

Arguments:

maxnetids - maximum number of netids (<= 20)

Returns:

slook - sync_lookent pointer on success

NULL - on failure (out of memory)

See Also:

sync_lookadd

sync_lookdel

sync_looksel

sync_lookclose

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_lookadd

Supported OS:

Windows NT

Function Prototype:

int sync_lookadd(sync_lookent *look, SCALLT *ct);

Description:

Add the file descriptor associated with ct to the selection list contained in look.

Arguments:

look - pointer to sync_lookent structure

ct - pointer to SCALLT to add

Returns:

0 - on success

-1 - on failure

See Also:

sync_lookinit

sync_looksel

sync_lookdel

sync_lookclose

sync_look

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_lookdel

Supported OS:

Windows NT

Function Prototype:

int sync_lookdel(sync_lookent *look, CALLT *ct);

Description:

Remove the file descriptor associated with ct from the selection list contained in look.

Arguments:

look - pointer to sync_lookent structure

ct - pointer to SCALLT to delete

Returns:

0 - on success

-1 - on failure

See Also:

sync_lookinit

sync_lookadd

sync_look

sync_looksel

sync_lookclose

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_looksel

Supported OS:

Windows NT

Function Prototype:

SCALLT *sync_looksel(sync_lookent *look, int tmout);

Description:

Checks for availability of a data frame for the netids in the selection list specified through sync_lookadds.

Arguments:

slook - pointer to sync_lookent structure

tmout - millisecs to wait (use -1 for infinity, 0 for no wait)

Returns:

ct - pointer to SCALLT if there is a frame to be read on the file descriptor associated with this SCALLT

NULL - nothing to read, or timeout

See Also:

sync_lookadd

sync_lookdel

sync_looksel

sync_lookclose

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_lookclose

Supported OS:

Windows NT

Function Prototype:

SCALLT *sync_lookclose(sync_lookent *look);

Description:

Closes the selection mechanism for look.

Arguments:

slook - pointer to sync_lookent structure

Returns:

NONE

See Also:

sync_lookinit

sync_lookadd

sync_lookdel

sync_looksel

[ NT vs 95 | Functions | Contents | Tags | Errors ]

Overview of Network Lookup Functions

Before using sync_getnetent the function sync_setnetent must be called which allocates necessary resources and enables the library to access the configuration database. At this point sync_getnetent can be used to scan through the list of synchronous netids in the system. An optional filter can be specified using sync_setfilter to limit or increase the types of Netids returned by sync_getnetent. To release the resources allocated by sync_setnetent call sync_endnetent.

The functions sync_getnetbynetid and sync_getnetbyname use the above functions to search through the configuration database to locate the desired Netid. These functions do not require the calling application to use sync_setnetent or sync_endnetent.

sync_setnetent

Supported OS:

Windows NT

Function Prototype:

void sync_setnetent(void)

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.

Arguments:

NONE

Returns:

NONE

See Also:

sync_endnetent

sync_getnetent

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_endnetent

Supported OS:

Windows NT

Function Prototype:

void sync_endnetent(void)

Description:

Ends packetnets database operations.

Arguments:

NONE

Returns:

NONE

See Also:

sync_setnetent

sync_getnetent

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_getnetent

Supported OS:

Windows NT

Function Prototype:

syncnetent *sync_getnetent(void)

Description:

Obtains one syncnetent entry from the packetnets database.

Arguments:

NONE

Returns:

NULL - on failure

pointer to syncnetent structure - on success

struct syncnetent {
    int		netid;    		/* network ID number */
    int		type;			/* network type */
    int		boardno;		/* board number */
    int		linkno;			/* link number */
    char	name[NETNETENTSZ];	/* network name */
    char	config[NETFILELENGTH];	/* configuration file */
    char	pktdev[NETNETDEVSZ];	/* Interface device */
};

See Also:

sync_setnetent

sync_endnetent

sync_setfilter

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_getnetbyname

Supported OS:

Windows NT

Function Prototype:

syncnetent *sync_getnetbyname(char *name)

Description:

Looks up a packetnets entry given a name.

Arguments:

name - network name to find

Returns:

NULL - on failure

pointer to syncnetent - on success

See Also:

sync_getnetbynetid

sync_getnetent

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_getnetbynetid

Supported OS:

Windows NT

Function Prototype:

syncnetent *sync_getnetbynetid(int netid)

Description:

Looks up a packetnets entry given a network ID.

Arguments:

netid - network ID to find

Returns:

NULL - on failure

pointer to syncnetent - on success

See Also:

sync_getnetbyname

sync_getnetent

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_setfilter

Supported OS:

Windows NT

Function Prototype:

void sync_setfilter(int typemask)

Description:

Sets a network type filter for all accesses to the packetnets database so that the functions sync_getnetent(), sync_getnetby...() will return only the specified network types. The default type for the sync_getnet...() functions is NETSYNC_TYPE. sync_open resets the default type to NETSYNC_TYPE.

Arguments:

typemask - Mask for Network types. ie. NETSYNC_TYPE | NETX25_TYPE
NETALL_TYPE will cause sync_getnet...(), to return all network types.

Returns:

NONE

See Also:

sync_getnetbynetid

sync_getnetbyname

sync_getnetent

[ NT vs 95 | Functions | Contents | Tags | Errors ]

Error Handling Functions

sync_error

Supported OS:

Windows NT

Function Prototype:

void sync_error(char *errstring)

Description:

Writes the error message associated with the most recent Synchronous Library Error code to stdout.

Use of stdout is restricted to Console (Text mode) Applications. For Win32 applications use sync_errorstr.

Arguments:

errstring - NULL or pointer to a string to prepend to the error message. A blank is inserted between the error string and the message.

Returns:

NONE

See Also:

sync_errorstr

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_errorstr

Supported OS:

Windows NT

Windows 95

Function Prototype:

int sync_errorstr(char *buf, int buflen)

Description:

Copies the error message associated with the most recent Synchronous Library Error code into buf.

Arguments:

buf - pointer to a string to hold the error message

buflen - length of buf

Returns:

0 - on success

-1 - on failure (not enough room in buf)

See Also:

sync_error

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_geterror

Supported OS:

Windows NT

Windows 95

Function Prototype:

int sync_geterror(void)

Description:

Retrieves the most recent Synchronous Library error code from the library.
For Windows NT, if the return value is SYS_SYSERR, a call to sync_getsyserror() will retrieve the system error defined in errno.h.

Arguments:

NONE

Returns:

0 - no error

SYE_ error code defined in libsync.h

See Also:

sync_getsyserror

sync_error

sync_errorstr

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_getsyserror

Supported OS:

Windows NT

Function Prototype:

int sync_getsyserror(void)

Description:

Retrieves the current system error code from the library.

Arguments:

NONE

Returns:

0 - no error

error from errno.h

See Also:

sync_geterror

sync_error

sync_errorstr

[ NT vs 95 | Functions | Contents | Tags | Errors ]

Adapter Statistics Functions

sync_openstats

Supported OS:

Windows NT

Function Prototype:

int sync_openstats(int netid, int type)

Description:

Open statistics request of type "type" on given Network ID.
Only one type of statistics request may be made at a time.

Arguments:

netid - network ID to find

type - currently only SYNC_BOARDSTATS

Returns:

0 - on sucess

-1 - on failure: type is not SYNC_BOARDSTATS

-2 - on failure: can't open device (no more devices available)

-3 - on failure: bad netid

See Also:

sync_getstats

sync_closestats

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_closestats

Supported OS:

Windows NT

Function Prototype:

void sync_closestats(void)

Description:

Close statistics request.

Arguments:

NONE

Returns:

NONE

See Also:

sync_openstats

sync_getstats

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_getstats

Supported OS:

Windows NT

Function Prototype:

int sync_getstats(int netid, char *buf, int len)

Description:

Obtain statistics of the type declared in sync_openstats into an adequately sized buffer buf of length len. The resulting buffer will contain a WANlinkstats structure as defined in brdstats.h.

Example:

#include "libsync.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();
}

Arguments:

netid - Network ID

buf - Pointer to buffer

len - length of buffer

Returns:

0 - on success

-1 - on failure: No open statistics (ie. use sync_openstats)

-2 - on failure: size mismatch for WANlinkstats

-3 - on failure: unable to complete statistics request

See Also:

sync_openstats

sync_closesstats

[ NT vs 95 | Functions | Contents | Tags | Errors ]

Miscellaneous Functions

sync_logmsg

Supported OS:

Windows NT

Function Prototype:

void sync_logmsg(char *format, ...)

Description:

Displays messages using stdout for Console Applications.

Arguments:

format - same format as printf function

... - values required to fill in format string

Returns:

NONE

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_setopts

Supported OS:

Windows NT

Windows 95

Function Prototype:

int sync_setopts(SCALLT *ct, TAG LIST)

int sync_setoptstags(SCALLT *ct, TAGS *tags)

Description:

Sets Synchronous library parameters.
Any function using tags arguments will internally call this function.

Tags recognized:

ST_VERBOSE

ST_BLOCK - Not supported under Windows NT

ST_OUTERR - Not supported under Windows NT

ST_LOGFILE - Not supported under Windows NT

ST_SETCRC - Enable/Disable CRC generation. (Sync/570 only)

ST_SETRTS - Set state of DTR

ST_SETDTR - Set state of RTS

Arguments:

ct - pointer to SCALLT

TAG LIST - tag pair list ending with TAG_END

tags - pointer to array of TAGS and values, terminated by TAG_END

Returns:

0

See Also:

sync_getopts

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_getopts

Supported OS:

Windows NT

Function Prototype:

int sync_getopts(SCALLT *ct, TAG LIST)

int sync_getoptstags(SCALLT *ct, TAGS *tags)

Description:

Obtains the value of Synchronous library parameters or parameters associated with a specific connection.

Arguments:

ct - pointer to SCALLT

TAG LIST - tag pair list ending with TAG_END

tags - pointer to TAGS list containing pointer to variables to hold information requested.

Tags recognized:

ST_VERBOSE

ST_BLOCK - Not supported under Windows NT

ST_OUTERR - Not supported under Windows NT

ST_LOGFILE - Not supported under Windows NT

ST_GETDSR - Get state of DSR

ST_GETCTS - Get state of CTS

ST_GETDCD - Get state of DCD

Returns:

0

See Also:

sync_setopts

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_findtag

Supported OS:

Windows NT

Windows 95

Function Prototype:

int sync_findtag(TAGS *tags, unsigned long item)

Description:

Finds the tag item in the tags array pointed to by tags.

Arguments:

tags - pointer to TAGS list

item - item to find in tags

Returns:

Index of the required tag item in the tags list

-1 - if not found.

See Also:

Tags

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_getdevtype

Supported OS:

Windows NT

Function Prototype:

int sync_getdevtype(int netid)

Description:

Get the type of physical device for Network netid.

Arguments:

netid - Network ID

Returns:

SGE, ARNET, etc. - declared in libsync.h

0 - not found or not available

See Also:

sync_getdevicename

[ NT vs 95 | Functions | Contents | Tags | Errors ]

sync_getdevicename

Supported OS:

Windows NT

Function Prototype:

int sync_getdevicename(int netid, char *name)

Description:

Get the device name of physical device for the Network netid.

Arguments:

netid - Network ID

name - pointer to string to hold the devicename, must be big enough!

Returns:

SGE, ARNET, etc. - declared in libsync.h

0 - not found or not available

See Also:

sync_getdevtype

[ NT vs 95 | Functions | Contents | Tags | Errors ]

Function Prototype:

void sync_setuservalue(SCALLT *ct, unsigned long value)

Description:

Associate a value with a SCALLT. This value may be retrieved by calling sync_getuservalue().

Arguments:

ct - pointer to SCALLT

value - the value to associate with ct

Returns:

NONE

See Also:

sync_getuservalue

Function Prototype:

unsigned long sync_getuservalue(SCALLT *ct)

Description:

Retrieve the value associated with SCALLT, set with sync_setuservalue().

Arguments:

ct - pointer to SCALLT

Returns:

NONE

value - the value to associate with ct

See Also:

sync_setuservalue