Creates an AGM library context and returns a handle to it. Also opens the configuration and report files specified.

DWORD agmOpen ( char *config,
char *report,
AGM_OPTIONS *options,
AGM_ERROR_HANDLER errorhandler,
AGMHD *agmhd)

config Pointer to a character string containing the name of the configuration file (e.g. ag.cfg).

report Pointer to a character string containing the name of the report file (e.g. ag.rpt).

options Pointer to an optional AGM_OPTIONS structure, or NULL. If the structure is provided, any field except size may be given a zero value to indicate that the default should be used. AGM_OPTIONS is defined as:

typedef struct
{
     DWORD  size ;
     DWORD  mode ;
     DWORD  maxwait ;
     DWORD  loadsize ;
     DWORD  testlevel ;
     DWORD  traceflags ;
     DWORD    reserved ;
 } AGM_OPTIONS ;

errorhandler Pointer to an error handler callback function, as described in the Details section.

agmhd Pointer to the returned AGM handle.

• SUCCESS
• AGMERR_FAILURE

This function opens an AGM context and returns a handle (agmhd) to the context for use in subsequent AGM library calls.

config is the name of a file containing the AG board configuration information. If the file is not present in the current directory, the file is searched for in the directories specified by the AGLOAD environment variable.

report is the name of the report file to which the configuration record (including information about hardware detected and files downloaded) is written. The report file is written in the current directory if the argument does not specify a full path name.

The fields of AGM_OPTIONS are:

Field	Description
size	The size of the structure.
mode	A bitmask of optional modes. The only mode currently supported is AGM_MODE_PARALLEL, which enables support for booting and downloading boards in parallel. See agmBootBoard for more information. Note: Parallel mode is not supported on non-threaded operating systems.
maxwait	A timeout interval (in seconds) for various device driver calls.
loadsize	The block size (in bytes) for data to be downloaded.
testlevel	A diagnostics level, from 1 to 3.
traceflags	Another diagnostic bitmask, equivalent to use of the utility agtrace with the same value.
reserved	Reserved. Always zero (0).

The errorhandler argument is a pointer to a function that is called when the AGM library encounters an error and needs to notify the caller about the error.

The AGM errorhandler function's prototype is:

typedef DWORD ( NMSSTDCALLPTR AGM_ERROR_HANDLER)
( AGMHD agmhd,
int boardnum,
DWORD severity,
char *errtxt)

The errorhandler function arguments are:

Argument	Description
agmhd	Handle returned by agmOpen.
boardnum	The number of the board to which the error applies, or -1 if it is not board-specific.
severity	Valid values are: · AGM_CALLBACK_ERROR · AGM_CALLBACK_WARNING · AGM_CALLBACK_INFORMATIONAL.
errtxt	Pointer to a character buffer containing error-specific text.

agmClose

/* An error handler callback to register with agmOpen(). */
DWORD NMSSTDCALL my_errorhandler(
    AGMHD agmhd,    /* AGM handle                                 */
    int   boardnum, /* The AG board number, or -1 if N/A          */
    DWORD severity, /* AGM_CALLBACK_{ERROR,WARNING,INFORMATIONAL} */
    char *errtxt )  /* Error text                                 */
{
    char *errtype;
    switch (severity)

    {
    case AGM_CALLBACK_ERROR:
        errtype = "ERROR";
        break;
    case AGM_CALLBACK_WARNING:
        errtype = "Warning";
        break;
    case AGM_CALLBACK_INFORMATIONAL:
        errtype = "Info";
        break;
    default:
        errtype = "<unknown severity>";
        break;
    }

 


    if (boardnum == -1)
        printf ("%s: %s\n", errtype, errtxt);
    else
        printf ("%s: [Board %d] %s", boardnum, errtype, errtxt);

    return SUCCESS;
} /* ErrorHandler