Calling the API through an assembler program

This topic discusses how to call the API using an assembler program.

Environment

To call the API, the calling program must be:

Language Environment AMODE 31
APF-authorized
Enabled for interrupts
Not holding any locks
In primary ASC mode (can also be in cross-memory mode)
Running in the same primary address space (PAS) as the event record and API1 control block

Call statement

[label] CZAPI1 event_record,CZAPI1CB

[label] CZAPI1 [event_record][,CZAPI1CB],MF=(E,label2)

label2 CZAPI1 [event_record][,CZAPI1CB],MF=L

Registers

When working with registers, common z/OS register conventions are observed and the following also apply:

Register 13 must point to the address of an 18-word save area for the API to use.
The API destroys the contents of registers 0, 1, 14, and 15; all other registers are preserved.
Register 15 contains a return code sent back to the calling program. A return code of 0 means success. For a detailed list, see Return codes.
Parameters specified as labels must be addressable, but the macro does not require a code base register.

Parameters

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

Parameter	Description
Event_record	Address of the event record or (with the exception of MF=L) a register (2) - (12) containing 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. This is a required parameter. In the case of an MF=E/MF=L pair, the value of the parameter might be supplied from either of the pair (sources).
CZAPI1CB	The address of the API1 control block or (with the exception of MF=L) a register (2) - (12) containing 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. This is a required parameter. In the case of an MF=E/MF=L pair, the value of the parameter might be supplied from either of the pair (sources).

Parameter

Description

Event_record

Address of the event record or (with the exception of MF=L) a register (2) - (12) containing 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.

This is a required parameter. In the case of an MF=E/MF=L pair, the value of the parameter might be supplied from either of the pair (sources).

CZAPI1CB

The address of the API1 control block or (with the exception of MF=L) a register (2) - (12) containing 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.

This is a required parameter. In the case of an MF=E/MF=L pair, the value of the parameter might be supplied from either of the pair (sources).

API1 control block

Following is a sample layout of the API1 control block fields:

* CZAPI1CB: Assembler layout of zDefender API 1 Control Block
* Passed as second parameter to API 1
Copyright_CZAPI1CB DSECT ,   So copyright notice comes over into header
DS C CZAPI1CB V5.9.1 Copyright 2014-2018,2019 BMC Software
DS C Don't edit CZAPI1CB.h -- edit CZAPI1CB and then use
DS C EDCDSECT to re-create the header file
*
CZAPI1CB DSECT ,
*
CZ1Ver   DS    AL1                 Control Block Version
CZ1Ver1    EQU   1                   Version 1
CZ1Ver2    EQU   2                   Version 2
CZ1Ver3    EQU   3                   Version 3 - Add CZ1IdentF
*
CZ1Flag1 DS    X                   Flags
CZ1F1FmtV    EQU X'80'               "LLBB" V-format - CZ1Lenth ignored
CZ1F1NoPurge EQU X'40'               No purge; return CZ1Reas_WdPurge
*
CZ1Inst DS    AL1                 Instance: 0 through 15
CZ1InstMax EQU   15                  Maximum instance number
*
CZ1Sev   DS    X                   Syslog Severity for message
CZ1SevDefault   EQU X'FF'            -1 - Default - Use Sev from TYPE
CZ1SevEmergency EQU 0                Emergency
CZ1SevAlert     EQU 1                Alert
CZ1SevCritical EQU 2                Critical
CZ1SevError     EQU 3                Error
CZ1SevWarning   EQU 4                Warning
CZ1SevNotice    EQU 5                Notice
CZ1SevInfo      EQU 6                Informational
CZ1SevDebug     EQU 7                Debug
*
CZ1Major DS    H                   Major type code
CZ1MajInt EQU   1                   Internal Events
CZ1MajDiag EQU   2                   Diagnostic Events
CZ1MajSMF EQU   3                   SMF Events
CZ1MajIFI EQU   4                   IFI Events
CZ1MajCons EQU   5                   Console Events
*          EQU   6                   Reserved for upward expansion
*          EQU   7                   Reserved for upward expansion
*          EQU   8                   Reserved for upward expansion
*          EQU   9                   Reserved for upward expansion
*          EQU   10                  Reserved for upward expansion
CZ1MajMinAPI1   EQU 11               Minimum allowed from API1
CZ1MajTest      EQU 11               API Testing
CZ1MajCorMisc   EQU 12               BMC AMI Various
CZ1MajCorIMS    EQU 13               BMC AMI IMS
CZ1MajCust      EQU 14               Reserved for use by customers
CZ1MajVIP       EQU 15               Vanguard Integrity Professionals
CZ1MajNewEra    EQU 16               NewEra Software, Inc.
CZ1MajSerena    EQU 17               Serena Software Inc.
CZ1MajCompuware EQU 18               Compuware Corporation
CZ1MajLog4j     EQU 19               Log4j user data
CZ1MajSPM       EQU 20               Security Policy Manager(SPM)
CZ1MajSIV       EQU 21               System Integrity Violation (SIV)
CZ1MajAO        EQU 22               AMI Ops
CZ1MajUserMsg   EQU 23               User Message
CZ1MajIMSConn   EQU 24               IMS Connect               AID-1140
*
CZ1Minor DS    H                   Minor type code
*
CZ1SubTp DS    H                   Subtype
*
CZ1Ident DS    H                   Optional event identifier
*
CZ1Lenth DS    F                   Record length if not CZ1F1FmtV
*
CZ1Fac   DS    F             Facility Code
CZ1FacKernel     EQU   0       Kernel messages
CZ1FacUser       EQU   1       User-level messages
CZ1FacMail       EQU   2       Mail System
CZ1FacSystem     EQU   3       System Daemons
CZ1FacSecurity4 EQU   4       Security/Authorization messages
CZ1FacSyslogd    EQU   5       Internally Generated SYSLOGD messages
CZ1FacPrinter    EQU   6       Line Printer Subsystem
CZ1FacNews       EQU   7       Network News Subsystem
CZ1FacUucp       EQU   8       UUCP Subsystem
CZ1FacClock9     EQU   9       Clock Daemon
CZ1FacSecurity10 EQU   10      Security/Authorization messages
CZ1FacFtp        EQU   11      FTP Daemon
CZ1FacNtp        EQU   12      NTP Daemon
CZ1FacLogaudit   EQU   13      Log Audit
CZ1FacLogalert   EQU   14      Log Alert
CZ1FacClock15    EQU   15      Clock Daemon
CZ1FacLocal0     EQU   16      Local Use 0 (SMF 110)
CZ1FacLocal1     EQU   17      Local Use 1 (IND$FILE Audit)
CZ1FacLocal2     EQU   18      Local Use 2 (MicroFocus ChangeMan)
CZ1FacLocal3     EQU   19      Local Use 3 (LSpace)
CZ1FacLocal4     EQU   20      Local Use 4 (Console)
CZ1FacLocal5     EQU   21      Local Use 5 (SMF 115/116)
CZ1FacLocal6     EQU   22      Local Use 6
CZ1FacLocal7     EQU   23      Local Use 7
*
CZ1IdentF DS    F                  Optional event id - Fullword
*
CZAPI1CB_Length EQU *-CZAPI1CB
*
* API1 Return Codes
CZ1Reas_Good     EQU X'0000' Good; success.
CZ1Reas_NoSlots EQU X'0401' No record slots available (retired)
CZ1Reas_WdPurge EQU X'0402' Would have caused purge but CZ1F1NoPurge
CZ1Reas_IsTerm   EQU X'0801' Instance not init or is terminating
CZ1Reas_API1is0 EQU X'0802' API1 address is zero (detected in macro)
CZ1Reas_CZVis0   EQU X'0803' CZ_Vector ptr zero (detected in macro)
CZ1Reas_CZVis0X EQU X'0804' CZ_Vector ptr zero (detected in exit)
CZ1Reas_NoAPI1   EQU X'0805' Exit revision number is less than 11
CZ1Reas_AVis0    EQU X'0806' Instance pointer zero (detected in macro)
CZ1Reas_AVis0X   EQU X'0807' Instance pointer zero (detected in exit)
CZ1Reas_NoRec    EQU X'0C01' API1 record pointer zero on entry to exit
CZ1Reas_NoCB     EQU X'0C02' API1CB pointer is zero on entry to exit
CZ1Reas_BadVer   EQU X'0C03' API1CB version is not 1 on entry to exit
CZ1Reas_BadMaj   EQU X'0C04' Event major code less than CZ1MajMinAPI1
CZ1Reas_BadInst EQU X'0C05' Instance < 0 or > 7 (detected in macro)
CZ1Reas_BadInstX EQU X'0C06' Instance < 0 or > 7 (detected in exit)
CZ1Reas_NoR1     EQU X'0C07' Register 1 is zero on entry to exit
CZ1Reas_NegLen   EQU X'0C08' Record length is non-positive
CZ1Reas_NoLic    EQU X'0C09' API1 Interface feature not licensed

Field descriptions

The fields are described in the following table:

Field name	Description
CZ1Ver	Identifies the version of the control block Must be specified as 1. You can also use one of the predefined equates for this field. For example, CZ1Ver1 identifies as version 1 of the control block.
CZ1Flag1	Event-record format flag Indicates the format of the event records. You can also use one of the predefined equates for this field: CZ1F1FmtV–When used, CZ1Lenth is ignored. The event record is in standard z/OS DFSMS variable length record format, beginning with a 4-byte, LLBB format, record control word (RCW). When omitted, the API refers to CZ1Lenth for the length of the event record. For more information, see CZ1Lenth. CZ1F1NoPurge–When used, the API does not enqueue the current record if the queue is full. No records are purged and the API sends the return code, CZ1Reas_WdPurge.
CZ1Inst	BMC AMI Defender instance The calling program sets this field to a value from 0 through 7. For more information, see Instances-of-BMC-AMI-Datastream. You can also use the predefined equate for this field: CZ1InstMax–Indicates the maximum number of allowed instances.
CZ1Sev	RFC 3164 severity for the syslog message The calling program sets this field to a valid severity. For more information about syslog severities, see Syslog-facilities-and-severities. You can also use one of the predefined equates for this field. For example, CZ1SevDefault–Indicates that the severity code defaults to the severity specified in the TYPE statement of the CZDEFINE member for the event type. Specifying CZ1SevDefault (-1) is the same as using the field.
CZ1Major	Specifies the major (generally organizational or administrative) event type Use one of the predefined equates for this field. 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.
CZ1Ident	Optional event identifier For information about the event identifier, see Event-identifier.
CZ1Lenth	Length of the event record Specifies the length of the event record. For more information on the length of event records, see Event record length in Event-record-considerations. This value can be overridden if CZ1F1FmtV is defined for CZ1Flag1.
CZ1Fac	RFC 3164 Facility code for the syslog message Indicates the facility that generated the event record, using a number from 0 through 23. You can also use one of the predefined equates for this field. For example, use CZ1FacUser to indicate user-level messages.

Return codes

After processing the event record, Register 15 contains a return code for 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 equates 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
00000C09	CZ1Reas_NoLic	The API1 Interface feature is not licensed
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 assembly language program, macros, and COPY members, see Sample assembler program.