Defining fields


You can modify any currently supported field definitions, and add support for new record types and fields for BMC AMI Datastream.


Related topics

Field-definition-file-statements

Planning

BMC AMI Datastream field definitions are not required for normal installation, configuration, usage, and maintenance of the product. For information about installation, see Installing.

Who should use the field definitions

As an advanced programmer, administrator, or security analyst, you can use

BMC AMI Datastream

field definitions to create or modify the definition of

BMC AMI Datastream

fields. You need thorough knowledge of the concepts and facilities described in this documentation .

Using the field definitions, you can do the following:

  • Define additional event record types for the agent to process (subject to some limitations). For example, you can define the processing of SMF Record Type 4, which is not currently supported by the agent.
  • Define additional fields in new or existing event record types. For example, you can define the fields of SMF Record Type 4, or additional fields in SMF Record Type 80, which is already supported by the agent.
  • Change the characteristics of existing fields. For example, the SMFXXSID field, which is the system identifier common to all SMF records, is a character field with the tag SID. You can redefine the SMFXXSID as a hex field, or redefine its tag as SysID.
  • Change other information associated with fields. For example, for SMF Record Type 80, the X'01' bit of the SMF80REA field is displayed as GLOBALAUDIT. You can change the display to Audited (Global).

For information about DSECT-to-field-definition conversion, see CZADEFBL-parameters.

Working with field definition files

Most users need not be concerned with the field definition files. You can ignore this section unless you meet at least one of the following criteria:

  • You are defining custom event fields.
  • You are using an ACF2 installation with one or all of the following conditions:
    • You have more than 80 bytes of user LID fields. Even if you do have more than 80 bytes of user LID fields, you can skip this section initially and deal with it later as an advanced topic.
    • You have custom defined fields in ACF2. In this case, you must create field definitions in BMC AMI Datastream to map to those custom fields.
  • You are using

    BMC AMI Datastream

    application program interface (API) with event records longer than 32768 bytes. Unless you are defining custom events, BMC Support tells you if this criterion applies to you.

Purpose

The Fields Definitions files contain the specifications of most of the events processed and fields formatted by

BMC AMI Datastream

. (Some event types and field definitions, such as the Counters, are hard-coded.) The Fields Definition file is not processed by CZASEND.

When the files are processed

The files are processed at the product start-up. Unlike the parameter file, there is no provision for rereading the field definition files without terminating and restarting the product. Any errors (but not warnings) detected while processing the fields definition files cause the product to terminate.

How the files are specified

By default, the Field Definition files begin with member CZDEFINE
 in the PDS(E) referenced by the CZAPARMS
CZPAO

 DD statement. You can override that default by specifying DEFS(filespec) in the PARM= parameter when the product starts, or DEFINES=filespec in the z/OS START command.

Example

You could say S CZAGENT,DEFINES='DD:MYDEFS(DEF1)' to make the file be the DEF1 member of the PDS(E) referenced by DD MYDEFS.

The START command and filespec is fully documented in START-command.

Preserving your modifications across BMC maintenance

Do not edit the any of the CZDxxxx PARM members of your PDS or PDSE, for example  CZDEFINE
, because they are replaced during and upgrade or reinstallation. Instead, copy any fields or specifications that you want to change and make all of your local modifications to CZDUSER1, CZDUSER2 and CZDUSER3. These PARM members are not replaced during upgrade or reinstallation.

It is possible to redefine any of the specifications in CZDEFINE
by using the RE- forms of the Field Definition statements as described.

See Format-of-parameter-and-field-definition-files.

Creating new field definitions for user-defined record types

(SPE2310)

Step

Description

 1

Use the CZADEFBL program to generate partially constructed field definitions from the IBM High Level Assembler (HLASM) DSECT macro that correspond to the new SMF or event record-type that you want to create. For information about how to use the CZADEFBL program, see Creating-field-definitions-with-the-CZADEFBL-program.

 2

Review the output from the CZADEFBL program and verify that it conforms to the field definitions from the HLASM DSECT macro. The HLASM DSECT macro is not maintained by BMC, so there might be differences between this macro and the CZADEFBL program.

 3

Modify the field definitions as required, specifically the DEF statement parameters such as Condition specifications, Format specifications, and Get specifications. For details, see DEF-and-REDEF-statements.

 4

In the amihlq.PARM data set, create a new PARM member for each record type you created. Use the following naming convention:

  • CZDSMFxx —SMF type xx
  • CZDxxx —Event type xxx

 5

Add the field definitions to their associated PARM member.

 6

In the amihlq.PARM data set, create another new PARM member for each record type you created. Use the following naming convention:

  • CZPSMFXX —SMF type xx
  • CZPXXX —Event type xxx

 7

Using the FIELDS parameter of the SMF statement (SMF type) or the EVENT statement (event type), add the list of fields to include in the SYSLOG that is sent to the SIEM. For more information, see General-SMF-record-type-statement and EVENT-statement.

 8

Add the SMF and EVENT statements to their associated CZPSMF or CZP PARM member.

 9

(Optional) Use the SWITCH statement in the $$$CONFG PARM member to enable sending the new SMF or EVENT record types to the SIEM; use the SELECT statement in the $$$SELCT PARM member to actually send them. Therefore, to send an SMF or EVENT record type to the SIEM, you must use both the SWITCH and SELECT statements. You cannot send a specific SMF or EVENT record by using the SELECT statement without a corresponding SWITCH statement set to ON.


Examples


SWITCH ON(SMF70)

BMC AMI Datastream is enabled to send (but doesn't actually send) SMF type 70 records to the SIEM.

SWITCH ON(SMF70)
SELECT IF(SMF70) FOR(SYSB) SMF(70)

If BMC AMI Datastream is running on SYSB software, the product actually sends the SMF type 70 records to the SIEM.

For more information, see SWITCH-statement and SELECT-and-DESELECT-statements .

 10

Use the %INCLUDE statement to add the names of the PARM members that you created earlier to the following PARM members:

  • CZDSMFxx  and CZDxxx  to amihlq.PARM(CZDUSER3)
  • CZPSMFxx  and CZPxxx  to amihlq.PARM(CZAFIELD)

For more information, see %INCLUDE statement.

RE- forms of the field definitions statements

All of the field definitions statements except CONFIG have a RE- form.

If you code the normal form of a field definitions statement that attempts to define a field that has already been defined, it results in an error.

If you code the RE- form that attempts to redefine a field that has not previously been defined, it results in a warning.

Example

The DEF statement has a form REDEF; the MAP statement is a form REMAP, and so forth. You can use the RE- forms to override the specifications of a previous statement.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*