Introduction
Functions
Example
Error Codes
Tags
Frame Reception Overview
Network Lookup Overview
Function Reference
Copyright © 1997-2004 The Software Group Limited
The Synchronous library allows a program to write synchronous data directly to a synchronous line. For raw framed synchronous links, the hardware adds/removes only start and end flags, zero bit insertion and a 16 bit CRC. For raw unframed synchronous links (only supported with some hardware), nothing is added to or removed from the data exchanged. In either case, 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!)
Whenever a function specifies that it accepts a TAG LIST, a variable length argument list is expected to be passed to it. A variation on this is to pass a pointer to the first element of an array of TAG structures to the ...tags() variant of this function.
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;
int buflen = 2048;
int rc, currentbuf;
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);
The second way involves passing an array of tags, which must still include a TAG_END. This method results in faster execution in most cases, since the library normally converts variable argument tags into an array form before processing them. You may wish to use this method when you are passing the same tags over and over again. Example:
SCALLT scallt;
char buf[2048];
TAGS mytags[] = { {ST_BUFFER, &buf[0]}, {ST_BUFLEN, 30}, {TAG_END, 0} };
int rc;
rc = sync_readtags(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.
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.
[ Functions | Introduction | Example | Errors | Tags | Reference ]
Please see Overview of Frame Reception Status Functions
These functions manipulate the file packetnets
database which stores network IDs and their network types
(protocols).
Please also see Overview of Network Lookup Functions
[ Functions | Introduction | Example | Errors | Tags | Reference ]
/***********************************************************************
* Module Name: libtest.c
*
* Description:
* Sends a string NUMTIMES times over a synchronous link
***********************************************************************/
#include <stdio.h>
#include "libsync.h"
#define NUMTIMES 100
int 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.
*/
ct = sync_open(netid, TAG_END));
if (!ct)
{
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);
}
[ Functions | Introduction | Example | Errors | Tags | Reference ]
The following is a list of error codes which sync_geterror() can return. 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.
[ Functions | Introduction | Example | Errors | Tags | Reference ]
This is a list of currently supported tags and an explanation of their meaning.
These can be passed to any function expecting tags.
[ Functions | Introduction | Example | Errors | Tags | Reference ]
The synchronous library has two mechanisms to determine the availability of data packets on one or more circuits.
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() andsync_lookdel() manipulate list entries,sync_looksel() queries the list for available data packets andsync_lookclose() frees the list.
[ Functions | Introduction | Example | Errors | Tags | Reference ]
The synchronous library requires that a netid be used to identify a particular board and link combination. The following group of functions enable access to the database which contains the netid information. These functions are only needed if the application wishes to investigate the current system configuration to dynamically determine the netid to use.
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 pointsync_getnetent() can be used to scan through the list of synchronous netids in the system. An optional filter can be specified usingsync_setfilter() to limit or increase the types of netids returned by sync_getnetent(). To release the resources allocated by sync_setnetent() callsync_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() orsync_endnetent().
[ Functions | Introduction | Example | Errors | Tags | Reference ]