This topic discusses how to call the API using a C or C++ program.

Environment

To call the API, the calling program must be:

• Language Environment AMODE 31
• Enabled for interrupts
• Not holding any locks
• In primary ASC mode (can also be in cross-memory mode)
• The event record and API1 control block must reside in the calling program’s primary address space (PAS)

These are normal conditions for a C or C++ program. The calling program must also be APF-authorized.

To compile and bind a C program with APF authorization, use the following example:

c89 –Wl,AC=1,EXTATTR=APF –o Sample Sample.c

Format

#include “CZAPI1.h”
int CZAPI1(const void *record, const struct CZAPI1CB *ctl_block) 

Parameters

The following table describes the parameters used in the previous example:

The API1 control block

Layout of the control block is defined in header file CZAPI1CB.h (automatically included by CZAPI1.h):

Struct CZAPI1CB {
unsigned char CZ1Ver; /* Control Block Version */
unsigned char CZ1Flag1; /* Flags */
unsigned char CZ1Inst; /* Instance: 0 through 7 */
unsigned char CZ1Sev; /* Syslog Severity for message */
short int CZ1Major; /* Major type code */
unsigned short CZ1Minor; /* Minor type code */
short int CZ1SubTp; /* Subtype */
unsigned char _filler1[2]; /* Filler */
int CZ1Lenth; /* Record length if not CZ1F1FmtV */
};

The fields are described in the following table:

Return code

After processing the event record, BMC AMI Defender sends a return code to the calling program. Zero indicates success. Non-zero values indicate errors. For example:

• 00000Cxx indicates a coding error
• 000008xx indicates an environmental error
• 000004xx indicates a temporary condition

The CZAPI1CB.h header file provides definitions for the names listed in the Symbolic column in the following table:

Sample program

For a sample C language program and header files, see Sample C program.