Sample assembler program
The sample assembly language program, associated macros, and COPY members are distributed in hlq.CZAGENT.ASM.
Source code
*PROCESS OVERRIDE(NORENT)
API1SAMP TITLE 'BMC AMI Agent for z/OS Sample Program for API1'
*
* Copyright 2014-2018,2019 BMC Software.
*
* This program is intended as an example only and may not represent
* BMC recommended programming practices. It is NOT reentrant.
* It must be link-edited into an APF-authorized library and with AC=1
API1TEST AMODE ANY31
API1TEST RMODE ANY
API1TEST CSECT
*
* Parameters that would be external in a real program
InstanceName DC CL16'SIEM.Agent' Agent running instance name
Repetitions EQU 5 Number of records to send
Severity EQU CZ1SevNotice Send with a severity of Notice
*
BEGIN SAVE (14,12)
LARL R12,API1TEST
USING API1TEST,R12
LR R2,R13
LA R13,SAVEAREA
ST R2,4(,R13)
ST R13,8(,R2)
USING CZAPI1CB,API_CB
*
* Initialize the API1CB with the version and instance number
XC CZAPI1CB(CZAPI1CB_Length),CZAPI1CB
MVI CZ1Ver,CZ1Ver1 Required
*
CLI InstanceName,C'0' Is the instance name alpha?
JL ItsAName Yes, it's a real name
IC R15,InstanceName Pick up the digit
NILL R15,X'0F' And off the zone bits
J InstanceGood Go store it
*
ItsAName EQU *
LA R1,InstanceName
BRAS R14,AgentInstFrName
LTR R15,R15 Did we succeed?
JNM InstanceGood
*
* Instance name not found
WTO 'Instance name not found',ROUTCDE=(11),DESC=12
LHI R15,16
J QUIT
*
InstanceGood EQU *
STC R15,CZ1Inst
*
* Initialize the API1CB for a diagnostic message
MVI CZ1Sev,CZ1SevInfo Print message as Info
MVI CZ1Major+1,CZ1MajDiag Major type "Diag"
MVI CZ1Minor+1,CZ1DiagMinSubstA Request substitution
*
USING CZ1DiagRec,DiagnosticArea
*
* Set up Message One
MVC CZ1DiagText(L'DiagMsg1),DiagMsg1 Move in text
LHI R2,L'DiagMsg1 Length of text
STH R2,CZ1DiagTextL Store in text length field
AHI R2,CZ1DiagFixedL Add length of fixed portion
ST R2,CZ1Lenth Length of event recd we are sending
*
* Substitution variables
LHI R0,5
ST R0,CZ1DiagWord1
ST R0,CZ1DiagWord2
LHI R0,1
ST R0,CZ1DiagWord3
LHI R0,1001
ST R0,CZ1DiagWord4
*
* Send the diagnostic message
CZAPI1 DiagnosticArea,API_CB
*
CHI R15,CZ1Reas_Good Check for total success
JNE QUIT Quit otherwise
*
* Set up Message Two
MVC CZ1DiagText(L'DiagMsg2),DiagMsg2 Move in text
LHI R2,L'DiagMsg2 Length of text
STH R2,CZ1DiagTextL Store in text length field
AHI R2,CZ1DiagFixedL Add length of fixed portion
ST R2,CZ1Lenth Length of event recd we are sending
*
* Substitution variables
LG R0,=FL8'123456789012345678' Big integer
STG R0,CZ1DiagDWord5 Doubleword five
MVC CZ1DiagChar8,=CL8'FooBar' String into Char 8
*
* Send the diagnostic message
CZAPI1 DiagnosticArea,API_CB
*
CHI R15,CZ1Reas_Good Check for total success
JNE QUIT Quit otherwise
*
* Initialize the API1CB for the data records
USING CZAPI1CB,API_CB
MVI CZ1Sev,Severity Arbitrary Syslog Severity
MVI CZ1Major+1,CZ1MajTest Major type "Test"
MVI CZ1Minor+1,1 Minor type 1
LHI R2,EVENT_REC_L
ST R2,CZ1Lenth Length of event recd we are sending
*
LHI R3,1 Repetition counter
*
LOOP EQU *
ST R3,A1SWORD Pass repetition number in record
*
CZAPI1 EVENT_REC,API_CB
*
CHI R15,CZ1Reas_Good Check for total success
JNE QUIT Quit otherwise
*
AHI R3,1
CHI R3,Repetitions
JNH LOOP
*
SR R15,R15
*
QUIT EQU *
L R13,4(,R13)
RETURN (14,12),T,RC=(15)
EJECT
* Find Instance number by name - prelikminary version
* Comparison is case-insensitive (assumes fairly vanilla EBCDIC)
* Linkage on R14
* Enter with R1 pointing to desired instance name, 16 bytes,
* padded with blanks if necessary
* Exit with R15 = found instance number 0 to 7 (low 32 bits)
* or -1 = name not found (includes no Agent running, etc.)
* No base register required. Reentrant.
* AMODE 31 or 64. PASN=HASN=SASN. Primary ASC.
* Destroys R0, R2 and R3, including potentially bits 0-31
* Assumes register equates R0-R15 defined
* Requires ZS-3 or above to assemble, and a z9 or above to run
* Comparison operates by XOR-ing the two values. If characters are
* equal (other than case) then no bits will be on except X'40' bits.
* Returns a false equal for certain obscure EBCDIC pairs such as
* (N<,\), ( ,B3), (£,C) and (^B#B%B7B)B'B6B<B=B>,0123456789)
&CZ_from_CTBL SETA x'1AC' Offset of our pointer to CZ_Vector
&MaxInst SETA 7 Maximum Instance number
&CZ_AgntInsts SETA 16+2+2 Offset of Instance ptrs in CZ_Vect
&AV_Revision SETA 16+4+1+1 Offset of revision in AVector
&exitRevWithName SETA 15 Minimum exit revision supports Names
&AV_InstName SETA 136 Offset of name in AVector
*
AgentInstFrName DS 0H
LGF R3,16(,0) Load CVT from PSA
LGF R3,X'8C'(,R3) Load ECVT from CVT
LGF R3,X'CC'(,R3) Customer Anchor Table from ECVT
ICM R3,B'1111',&CZ_from_CTBL.(R3) BMC AMI ptr f/Cust Anch
JZ AgentInstNoAgent No agent is running
LGFR R3,R3 Extend to 64 bits
*
LGHI R15,&MaxInst+1 Always one higher than instance
AgentInstFrNameLoop EQU *
* Searches in reverse order, 7 to 0, FWIW
SLLG R2,R15,2 Instance num X size of each pointer
LGF R2,&CZ_AgntInsts-4(R2,R3) Load virtual instance pointer
LTGR R2,R2 Is there any?
JZ AgentInstFrNameNext No, on to the next name
*
* Instance here, does it have a name at all?
LH R0,&AV_Revision.(,R2) Load exit revsion number
CHI R0,&exitRevWithName Is it great enough?
JL AgentInstFrNameNext No, too old
*
* Compare the two names - case independent
LG R0,0(,R1) Load first half of supplied name
XG R0,&AV_InstName.(,R2) XOR with this instance name
NIHF R0,X'BFBFBFBF' Turn off the X'40' bits
NILF R0,X'BFBFBFBF' Turn off the X'40' bits
LTGR R0,R0 Test *all* of the bits
JNZ AgentInstFrNameNext Some others were on
*
LG R0,8(,R1) Load second half of supplied name
XG R0,&AV_InstName+8(,R2) XOR with this instance name
NIHF R0,X'BFBFBFBF' Turn off the X'40' bits
NILF R0,X'BFBFBFBF' Turn off the X'40' bits
LTGR R0,R0 Test *all* of the bits
JZ AgentInstFrNameFound None on, return, instance+1 in R15
*
AgentInstFrNameNext EQU * On to the next (previous!) instance
JCT R15,AgentInstFrNameLoop Until have done all 8
*
* Failure
AgentInstNoAgent EQU *
LHI R15,-1 So indicate
BR R14 And return
*
* Found
AgentInstFrNameFound EQU *
AHI R15,-1 Get actual instance number
BR R14 And return
EJECT
*
SAVEAREA DS 18F
API_CB DS 0F,(CZAPI1CB_Length)X
*
EVENT_REC DS 0F
A1SDWord DC FL8'1234' Example of a doubleword (64-bit)
* integer field
A1SWord DC F'0' Example of a fullword (32-bit)
* integer field. The sample program
* stores the repetition number here
A1SHWord DC H'-52' Example of a halfword signed
* integer field
A1SByte DC AL1(17) Example of an 8-bit integer field
A1SChar DC CL20'Char Field' Example of a fixed-length character
* field
A1SBit DC Al1(A1sFemale+A1SMarried+A1SGrad) Example of a Bit
* flag field
A1SFemale EQU X'40' Female
A1SMarried EQU X'08' Married
A1SGrad EQU X'04' College Graduate
A1SCitizen EQU X'02' Citizen
A1SEmploy EQU X'01' Employed
*
A1SDesc DC AL1(A1SDEast) Example of a Description field
A1SDNorth EQU 1 Example values for A1SDesc
A1SDSouth EQU 2
A1SDEast EQU 3
A1SDWest EQU 4
*
A1SSparse DC AL2(A1SSOpen) Example of Description Field that
* makes sparse utilization of the
* bits occupied by the field
A1SSOpen EQU C'OP' Assumed code for "Open"
A1SSClose EQU C'CL' Assumed code for "Closed"
EVENT_Rec_L EQU *-EVENT_REC
*
* Area for Diagnostic messages
DiagnosticArea DS 0F
DS XL(CZ1DiagLength)
*
* Diagnostic messages
DiagMsg1 DC C'API1SAMP Starting. Version %1$d.%2$d.%3$d.%4$d'
DiagMsg2 DC C'Magic number is %5$lld; word of the day is %8$.6s.'
*
COPY CZAPI1CB
COPY CZAPI1DG
* Register equates
R0 EQU 0
R1 EQU 1
R2 EQU 2
R3 EQU 3
R4 EQU 4
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
END BEGIN
API1SAMP TITLE 'BMC AMI Agent for z/OS Sample Program for API1'
*
* Copyright 2014-2018,2019 BMC Software.
*
* This program is intended as an example only and may not represent
* BMC recommended programming practices. It is NOT reentrant.
* It must be link-edited into an APF-authorized library and with AC=1
API1TEST AMODE ANY31
API1TEST RMODE ANY
API1TEST CSECT
*
* Parameters that would be external in a real program
InstanceName DC CL16'SIEM.Agent' Agent running instance name
Repetitions EQU 5 Number of records to send
Severity EQU CZ1SevNotice Send with a severity of Notice
*
BEGIN SAVE (14,12)
LARL R12,API1TEST
USING API1TEST,R12
LR R2,R13
LA R13,SAVEAREA
ST R2,4(,R13)
ST R13,8(,R2)
USING CZAPI1CB,API_CB
*
* Initialize the API1CB with the version and instance number
XC CZAPI1CB(CZAPI1CB_Length),CZAPI1CB
MVI CZ1Ver,CZ1Ver1 Required
*
CLI InstanceName,C'0' Is the instance name alpha?
JL ItsAName Yes, it's a real name
IC R15,InstanceName Pick up the digit
NILL R15,X'0F' And off the zone bits
J InstanceGood Go store it
*
ItsAName EQU *
LA R1,InstanceName
BRAS R14,AgentInstFrName
LTR R15,R15 Did we succeed?
JNM InstanceGood
*
* Instance name not found
WTO 'Instance name not found',ROUTCDE=(11),DESC=12
LHI R15,16
J QUIT
*
InstanceGood EQU *
STC R15,CZ1Inst
*
* Initialize the API1CB for a diagnostic message
MVI CZ1Sev,CZ1SevInfo Print message as Info
MVI CZ1Major+1,CZ1MajDiag Major type "Diag"
MVI CZ1Minor+1,CZ1DiagMinSubstA Request substitution
*
USING CZ1DiagRec,DiagnosticArea
*
* Set up Message One
MVC CZ1DiagText(L'DiagMsg1),DiagMsg1 Move in text
LHI R2,L'DiagMsg1 Length of text
STH R2,CZ1DiagTextL Store in text length field
AHI R2,CZ1DiagFixedL Add length of fixed portion
ST R2,CZ1Lenth Length of event recd we are sending
*
* Substitution variables
LHI R0,5
ST R0,CZ1DiagWord1
ST R0,CZ1DiagWord2
LHI R0,1
ST R0,CZ1DiagWord3
LHI R0,1001
ST R0,CZ1DiagWord4
*
* Send the diagnostic message
CZAPI1 DiagnosticArea,API_CB
*
CHI R15,CZ1Reas_Good Check for total success
JNE QUIT Quit otherwise
*
* Set up Message Two
MVC CZ1DiagText(L'DiagMsg2),DiagMsg2 Move in text
LHI R2,L'DiagMsg2 Length of text
STH R2,CZ1DiagTextL Store in text length field
AHI R2,CZ1DiagFixedL Add length of fixed portion
ST R2,CZ1Lenth Length of event recd we are sending
*
* Substitution variables
LG R0,=FL8'123456789012345678' Big integer
STG R0,CZ1DiagDWord5 Doubleword five
MVC CZ1DiagChar8,=CL8'FooBar' String into Char 8
*
* Send the diagnostic message
CZAPI1 DiagnosticArea,API_CB
*
CHI R15,CZ1Reas_Good Check for total success
JNE QUIT Quit otherwise
*
* Initialize the API1CB for the data records
USING CZAPI1CB,API_CB
MVI CZ1Sev,Severity Arbitrary Syslog Severity
MVI CZ1Major+1,CZ1MajTest Major type "Test"
MVI CZ1Minor+1,1 Minor type 1
LHI R2,EVENT_REC_L
ST R2,CZ1Lenth Length of event recd we are sending
*
LHI R3,1 Repetition counter
*
LOOP EQU *
ST R3,A1SWORD Pass repetition number in record
*
CZAPI1 EVENT_REC,API_CB
*
CHI R15,CZ1Reas_Good Check for total success
JNE QUIT Quit otherwise
*
AHI R3,1
CHI R3,Repetitions
JNH LOOP
*
SR R15,R15
*
QUIT EQU *
L R13,4(,R13)
RETURN (14,12),T,RC=(15)
EJECT
* Find Instance number by name - prelikminary version
* Comparison is case-insensitive (assumes fairly vanilla EBCDIC)
* Linkage on R14
* Enter with R1 pointing to desired instance name, 16 bytes,
* padded with blanks if necessary
* Exit with R15 = found instance number 0 to 7 (low 32 bits)
* or -1 = name not found (includes no Agent running, etc.)
* No base register required. Reentrant.
* AMODE 31 or 64. PASN=HASN=SASN. Primary ASC.
* Destroys R0, R2 and R3, including potentially bits 0-31
* Assumes register equates R0-R15 defined
* Requires ZS-3 or above to assemble, and a z9 or above to run
* Comparison operates by XOR-ing the two values. If characters are
* equal (other than case) then no bits will be on except X'40' bits.
* Returns a false equal for certain obscure EBCDIC pairs such as
* (N<,\), ( ,B3), (£,C) and (^B#B%B7B)B'B6B<B=B>,0123456789)
&CZ_from_CTBL SETA x'1AC' Offset of our pointer to CZ_Vector
&MaxInst SETA 7 Maximum Instance number
&CZ_AgntInsts SETA 16+2+2 Offset of Instance ptrs in CZ_Vect
&AV_Revision SETA 16+4+1+1 Offset of revision in AVector
&exitRevWithName SETA 15 Minimum exit revision supports Names
&AV_InstName SETA 136 Offset of name in AVector
*
AgentInstFrName DS 0H
LGF R3,16(,0) Load CVT from PSA
LGF R3,X'8C'(,R3) Load ECVT from CVT
LGF R3,X'CC'(,R3) Customer Anchor Table from ECVT
ICM R3,B'1111',&CZ_from_CTBL.(R3) BMC AMI ptr f/Cust Anch
JZ AgentInstNoAgent No agent is running
LGFR R3,R3 Extend to 64 bits
*
LGHI R15,&MaxInst+1 Always one higher than instance
AgentInstFrNameLoop EQU *
* Searches in reverse order, 7 to 0, FWIW
SLLG R2,R15,2 Instance num X size of each pointer
LGF R2,&CZ_AgntInsts-4(R2,R3) Load virtual instance pointer
LTGR R2,R2 Is there any?
JZ AgentInstFrNameNext No, on to the next name
*
* Instance here, does it have a name at all?
LH R0,&AV_Revision.(,R2) Load exit revsion number
CHI R0,&exitRevWithName Is it great enough?
JL AgentInstFrNameNext No, too old
*
* Compare the two names - case independent
LG R0,0(,R1) Load first half of supplied name
XG R0,&AV_InstName.(,R2) XOR with this instance name
NIHF R0,X'BFBFBFBF' Turn off the X'40' bits
NILF R0,X'BFBFBFBF' Turn off the X'40' bits
LTGR R0,R0 Test *all* of the bits
JNZ AgentInstFrNameNext Some others were on
*
LG R0,8(,R1) Load second half of supplied name
XG R0,&AV_InstName+8(,R2) XOR with this instance name
NIHF R0,X'BFBFBFBF' Turn off the X'40' bits
NILF R0,X'BFBFBFBF' Turn off the X'40' bits
LTGR R0,R0 Test *all* of the bits
JZ AgentInstFrNameFound None on, return, instance+1 in R15
*
AgentInstFrNameNext EQU * On to the next (previous!) instance
JCT R15,AgentInstFrNameLoop Until have done all 8
*
* Failure
AgentInstNoAgent EQU *
LHI R15,-1 So indicate
BR R14 And return
*
* Found
AgentInstFrNameFound EQU *
AHI R15,-1 Get actual instance number
BR R14 And return
EJECT
*
SAVEAREA DS 18F
API_CB DS 0F,(CZAPI1CB_Length)X
*
EVENT_REC DS 0F
A1SDWord DC FL8'1234' Example of a doubleword (64-bit)
* integer field
A1SWord DC F'0' Example of a fullword (32-bit)
* integer field. The sample program
* stores the repetition number here
A1SHWord DC H'-52' Example of a halfword signed
* integer field
A1SByte DC AL1(17) Example of an 8-bit integer field
A1SChar DC CL20'Char Field' Example of a fixed-length character
* field
A1SBit DC Al1(A1sFemale+A1SMarried+A1SGrad) Example of a Bit
* flag field
A1SFemale EQU X'40' Female
A1SMarried EQU X'08' Married
A1SGrad EQU X'04' College Graduate
A1SCitizen EQU X'02' Citizen
A1SEmploy EQU X'01' Employed
*
A1SDesc DC AL1(A1SDEast) Example of a Description field
A1SDNorth EQU 1 Example values for A1SDesc
A1SDSouth EQU 2
A1SDEast EQU 3
A1SDWest EQU 4
*
A1SSparse DC AL2(A1SSOpen) Example of Description Field that
* makes sparse utilization of the
* bits occupied by the field
A1SSOpen EQU C'OP' Assumed code for "Open"
A1SSClose EQU C'CL' Assumed code for "Closed"
EVENT_Rec_L EQU *-EVENT_REC
*
* Area for Diagnostic messages
DiagnosticArea DS 0F
DS XL(CZ1DiagLength)
*
* Diagnostic messages
DiagMsg1 DC C'API1SAMP Starting. Version %1$d.%2$d.%3$d.%4$d'
DiagMsg2 DC C'Magic number is %5$lld; word of the day is %8$.6s.'
*
COPY CZAPI1CB
COPY CZAPI1DG
* Register equates
R0 EQU 0
R1 EQU 1
R2 EQU 2
R3 EQU 3
R4 EQU 4
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
END BEGIN
Field definitions
TYPE API_Test1() API1GENERAL( +
CEF( NAME(CEF_Test_1_Name) ) +
MAJOR(4) MINOR(1) PROCESS('Test1') FACILITY(Syslogd) )
BITS B_A1SBit UChar X'40'(Female) X'8'(Married) +
X'4'("College graduate") X'2'(Citizen) X'1'(Employed)
MAP M_A1SDesc E(1 North) E(2 South) E(3 East) E(4 West)
MAP M_A1SSparse E('OP' Open) E('CL' Closed)
DEF A1SDWord DWord API_Test1() FInt(ULongLong) GBase(X'0' 8)
DEF A1SWord Rep API_Test1() FInt(ULong) GBase(X'8' 4)
DEF A1SHWord HWord API_Test1() FInt(Short) GBase(X'C'2)
DEF A1SByte Byte API_Test1() FInt(UChar) GBase(X'E' 1)
DEF A1SChar Char API_Test1() FChar(20) GBase(X'F' 20)
DEF A1SBit Bit API_Test1() FBits(B_A1SBit UChar) GBase(X'23' 1)
DEF A1SDesc Desc API_Test1() FDesc(M_A1SDesc UChar) GBase(X'24' 1)
DEF A1SSparse Sparse API_Test1() FDesc(M_A1SSparse UShort)
GBase(X'25' 2)
CEF( NAME(CEF_Test_1_Name) ) +
MAJOR(4) MINOR(1) PROCESS('Test1') FACILITY(Syslogd) )
BITS B_A1SBit UChar X'40'(Female) X'8'(Married) +
X'4'("College graduate") X'2'(Citizen) X'1'(Employed)
MAP M_A1SDesc E(1 North) E(2 South) E(3 East) E(4 West)
MAP M_A1SSparse E('OP' Open) E('CL' Closed)
DEF A1SDWord DWord API_Test1() FInt(ULongLong) GBase(X'0' 8)
DEF A1SWord Rep API_Test1() FInt(ULong) GBase(X'8' 4)
DEF A1SHWord HWord API_Test1() FInt(Short) GBase(X'C'2)
DEF A1SByte Byte API_Test1() FInt(UChar) GBase(X'E' 1)
DEF A1SChar Char API_Test1() FChar(20) GBase(X'F' 20)
DEF A1SBit Bit API_Test1() FBits(B_A1SBit UChar) GBase(X'23' 1)
DEF A1SDesc Desc API_Test1() FDesc(M_A1SDesc UChar) GBase(X'24' 1)
DEF A1SSparse Sparse API_Test1() FDesc(M_A1SSparse UShort)
GBase(X'25' 2)
Parameter file statement
EVENT TEST1 FIELDS( +
A1SDWord +
A1SWord +
A1SHWord +
A1SByte +
A1SChar +
A1SBit +
A1SDesc +
A1SSparse +
IEF_EXIT +
CURRENT_TIME +
)
A1SDWord +
A1SWord +
A1SHWord +
A1SByte +
A1SChar +
A1SBit +
A1SDesc +
A1SSparse +
IEF_EXIT +
CURRENT_TIME +
)
Sample syslog output
The following message would be repeated five times, with Rep varying from 1 to 5:
Aug 20 10:25:17 mvssysb Test1: DWord: 1234 - Rep: 1 - HWord:
-52 - Byte: 17 - Char: Char Field - Bit: {College graduate, Married, Female} -
Desc: East - Sparse: Open
-52 - Byte: 17 - Char: Char Field - Bit: {College graduate, Married, Female} -
Desc: East - Sparse: Open
Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*