Calling the API through a C or C++ program

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:

Parameters	Description
record	The address of the event record The format of the event record is not specified by the API. The event record is read-only to the API and is not modified. For more information, see Event-records.
Ctl_block	The address of the API1 control block The calling program must initialize all of the fields of the control block (except optional fields) before calling the API. The API1 control block is read-only to the API and is not modified.

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:

Field name	Description
CZ1Ver	Version of the control block Must be specified as 1.
CZ1Flag1	Event-record format flag Indicates the format of the event records.
CZ1Inst	BMC AMI Defender instance The calling program sets this field to a value 0 through 7. For more information, see Instances-of-BMC-AMI-Datastream.
CZ1Sev	RFC 3164 severity for the formatted syslog message The calling program sets this field to a valid syslog severity. For more information on syslog severities, see Syslog-facilities-and-severities.
CZ1Major	Specifies the major (generally organizational or administrative) event type For information about major event types, see Event types in Event-record-considerations.
CZ1Minor	Specifies the minor (generally a subdivision of a major) event type For information about minor event types, see Event types in Event-record-considerations.
CZ1SubTp	Specifies the subtype (generally a subdivision of a minor) event type For information about subtype event types, see Event types in Event-record-considerations.
_filler1[2]	Filler of length 2
CZ1Lenth	Length of the event record Specifies the length of the event record. For more information about the length of event records, see Event record length in Event-record-considerations. This value can be overridden if CZ1F1FmtV is defined for CZ1Flag1.

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:

Return code (Hex)	Symbolic	Description
00000000	CZ1Reas_Good	The status is good or the process completed successfully
00000C01	CZ1Reas_NoRec	API1 record pointer is zero on entry to exit
00000C02	CZ1Reas_NoCB	API1CB pointer is zero on entry to exit
00000C03	CZ1Reas_BadVer	API1CB version is not 1 on entry to exit
00000C04	CZ1Reas_BadMaj	The event record major type value is less than CZ1MajMinAPI1
00000C05	CZ1Reas_BadInst	The instance number is less than zero or greater than seven (detected in macro)
00000C06	CZ1Reas_BadInstX	The instance number is less than zero or greater than seven (detected in exit)
00000C07	CZ1Reas_NoR1	Register 1 is zero on entry to exit
00000C08	CZ1Reas_NegLen	Record length is negative
00000401	CZ1Reas_NoSlots	(Retired) No record slots are available
00000402	CZ1Reas_WdPurge	No purge because CZ1F1NoPurge is in use
00000801	CZ1Reas_IsTerm	BMC AMI Defender instance is not yet initialized or is terminating
00000802	CZ1Reas_API1is0	API1 entry address in a Vector is zero; this should not occur (detected in macro)
00000803	CZ1Reas_CZVis0	CZ_Vector pointer zero; no instances of BMC AMI Defender running (detected in macro)
00000804	CZ1Reas_CZVis0X	CZ_Vector pointer zero; no instances of BMC AMI Defender running (detected in exit)
00000805	CZ1Reas_NoAPI1	Exit revision number is less than 11; exit (and by implication, associated BMC AMI Defender version) does not support API1
00000806	CZ1Reas_Avis0	Instance Avector pointer is zero; specified instance is not running (detected in macro)
00000807	CZ1Reas_Avis0X	Instance Avector pointer is zero; specified instance is not running (detected in exit)

Sample program

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