Using API1 Subsystem Writer
The benefits of using the API1 Subsystem Writer over writing your own API1 interface program are:
- The interface can be SAF-secured using RACF, ACF2, or Top Secret
- It can be used by most IBM or third-party vendor utilities that write output using a standard IBM QSAM interface
- It does not require APF authorization for the caller
This topic contains the following information:
Enabling API1 Subsystem Writer
To enable API1 Subsystem Writer, specify the target subsystem of the BMC AMI Datastream agent address space in the DD statement for the output file.
Using z/OS SAF
You can use System Authorization Facility (SAF) security to validate users and groups accessing your agent's resource data sets. To do this, configure the following parameters in the CZAGENT JCL:
SECCLS—Indicates the security class your system uses. Accepted classes are DATASET (for RACF and Top Secret) and APPL (for ACF2).
- SECPFX—Specifies a unique prefix that, when added to the subsystemName and LOADFILE parameters, builds a data set name for the agent address space, which can be used by security systems, such as RACF and Top Secret. For example, if you specify the prefix AMIZOS.AGT for subsystemName CZAS, the data set name is AMIZOS.AGT.CZAS.LOADFILE on volume BMCSEC.
After you configure the SECCLS and SECPFX parameters, your z/OS Security Administrator can define the user IDs and groups that are permitted to access the resource.
For more information about the SECCLS and SECPFX parameters, see Sample-CZAGENT-JCL-for-running-BMC-AMI-Datastream-as-a-started-task.
DD statement parameters
As shown in the example in Enabling API1 Subsystem Writer, the first SUBSYS parameter must be the subsystem name of the BMC AMI Datastream agent.
The second parameter must be API1 enclosed in single quotation marks. You must enclose additional Subsystem Writer subparameters in single quotation marks and separate them by commas.
For more information about the SUBSYS parameter, see the section about the SUBSYS parameter in the IBM z/OS MVS JCL Reference manual.
Subsystem Writer subparameters
API1 Subsystem Writer uses the following optional subparameters:
Parameter | Description | ||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
FACILITY(facilityName|facilityNumber) | Indicates the RFC3164 message type for the syslog messages For information about facility codes, see Syslog-facilities-and-severities. If you omit FACILITY, the default LOCAL1 (17 – Local Use 1 (IND$FILE Audit)) is used. | ||||||||||||||||||||||||||||||||||||||||||
MAJOR(majorName|majorNumber) | Major code used to uniquely identify the functional purpose of the records You can choose from the following codes:
If you omit MAJOR, the default CorMisc (12) is used. | ||||||||||||||||||||||||||||||||||||||||||
MAXWAIT(numberOfSeconds) | The maximum number of seconds, from 0 to 86400, to wait for sufficient queue space to become available before bypassing the command to add the message to the queue If there is not enough room in the queue (see the SLACK parameter), the Subsystem Writer recalculates the available space every 0.25 of a second until the total number of seconds expires. MAXWAIT(0) waits for a very long time (actually, 4,294,967,295 seconds or approximately 136 years). If you omit MAXWAIT, the default 300 is used. | ||||||||||||||||||||||||||||||||||||||||||
MINOR(minorNumber) | From 0 to 32767, provides additional granularity for identifying records You can create your own message TYPE definitions for specific MINOR codes. For more information, see General-SMF-record-type-statement. If you omit MINOR, the default 11 is used. | ||||||||||||||||||||||||||||||||||||||||||
PURGE(YES|NO) | Indicates whether to purge old records from the queue in order to add a new record Generally, you shouldn't discard real-time security (SMF and EVENT data) records for API1 messages. Use this option only if you have a reason to force messages onto the queue. If you omit PURGE, the default NO is used. | ||||||||||||||||||||||||||||||||||||||||||
SEVERITY(severityName|severityNumber) | Syslog severity code for the forwarded messages For information about severity codes, see Syslog-facilities-and-severities. If you omit SEVERITY, the default severity code from the TYPE statement is used. For more information, see TYPE-and-RETYPE-statements. | ||||||||||||||||||||||||||||||||||||||||||
SLACK(percentageOfQueue) | The percentage, from 0 to 100, of the total queue space that must be available before adding new records to the queue If you omit SLACK, the default 50 is used. | ||||||||||||||||||||||||||||||||||||||||||
SUBTYPE(subtype) | From 0 to 32767, provides additional granularity for identifying data fields in the records You can create your own message field definitions for specific SUBTYPE codes. For more information, see General-SMF-record-type-statement. If you omit SUBTYPE, the default 0 is used. |
Subsystem Writer example
In the following example, we pass the JES SYSOUT messages to the active BMC AMI Datastream agent CZAT subsystem. We want messages only with a specific string of characters.
// 'MAJOR(CUST)',
// 'MINOR(99)',
// 'SUBTYPE(22)',
// 'FACILITY(USER)',
// 'SEVERITY(CRITICAL)'),
// DCB=RECFM=V
Limitations
Files routed to the Subsystem Writer are routed directly to the BMC AMI Datastream agent and out to the SIEM. They are not available for downstream processing by subsequent jobs or jobsteps because no physical file is created.