endevor api an introduction to the endevor application programming interface
DESCRIPTION
An introduction to the CA Endevor Application Programming Interface with examples using COBOL and REXX.TRANSCRIPT
Endevor API
An Introduction to the Endevor Application Programming Interface
Kevin Grimes, PresidentCA Endevor Global User Community
3) Some Examples
2) Architecture
1) What good is the API?
Agenda
1 What Goodis the API?
What is an API?
What functions are supported?• Inventory Query and List Functions
• Element Extract
• Element Actions
• Package Actions
• and almost any Endevor function
“Emptiness which is conceptually liable to be mistaken for sheer nothingness is in fact the reservoir of infinite possibilities.”
~ Daisetz Suzuki
2 Architecture
Calling the API from a COBOL Program
List and Extract Function Call
CALL EAC-CASCMMF-APINAME USING AACTL ALELM-RQ ALELM-RS.
Element Action Function Call
CALL EAC-CASCMMF-APINAME USING AACTL AEGEN-RQ.
Sample Applications
Source Code Only:•CCIDRPT1
•ENHAAPGM
•ENHAEPGM
•ENHAPLST
•ENHAPUPD
Load Module Only:•ENTBJAPI
3 Examples
SCL API FunctionThe jack of all trades
IDENTIFICATION DIVISION.
PROGRAM-ID. KGAPISCL.
*REMARKS. THIS PROGRAM CALLS THE ENDEVOR API
* USING PRE-FORMATTED SCL.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT INPUT-FILE ASSIGN TO UR-S-APISCLIN
FILE STATUS IS APISCLIN-FILE-STATUS
ACCESS IS SEQUENTIAL.
DATA DIVISION.
FILE SECTION.
FD INPUT-FILE
RECORDING MODE IS F
LABEL RECORDS ARE OMITTED.
01 INPUT-RECORD.
05 FILLER PIC X(80).
WORKING-STORAGE SECTION.
01 WS-INPUT-RECORD.
05 WS-INPUT-RECORD-DATA PIC X(80).
01 INPUT-FILE-STATUS PIC X VALUE 'N'.
88 INPUT-EOF VALUE 'Y'.
01 WS-VARIABLES.
05 SUB1 PIC 99 VALUE 0.
05 APISCLIN-FILE-STATUS PIC XX.
88 TASK-SUCCESSFUL-APISCLIN VALUE '00'.
88 END-OF-APISCLIN VALUE '10'.
88 UNDEFINED-ERROR-APISCLIN VALUES ARE '23' THRU '99'.
05 WS-RETURN-CODE PIC 9(4) VALUE ZEROS.
COPY ECCCNST.
COPY ECHAACTL.
COPY ECHAUSCL.
LINKAGE SECTION.
01 LS-PARM.
05 LS-PARM-LENGTH PIC 9(4) COMP.
05 LS-SCL-TYPE PIC X.
PROCEDURE DIVISION USING LS-PARM.
MAIN-LINE.
INITIALIZE AUSCL-RQ-DATAAREA.
MOVE LS-SCL-TYPE TO AUSCL-RQ-SCLTYPE.
OPEN INPUT INPUT-FILE.
READ INPUT-FILE INTO WS-INPUT-RECORD
AT END MOVE 'Y' TO INPUT-FILE-STATUS
END-READ.
PERFORM UNTIL INPUT-EOF
ADD +1 TO SUB1
MOVE WS-INPUT-RECORD TO AUSCL-RQ-SCL(SUB1)
READ INPUT-FILE INTO WS-INPUT-RECORD
AT END MOVE 'Y' TO INPUT-FILE-STATUS
END-READ
END-PERFORM.
INITIALIZE AACTL-DATAAREA.
MOVE 'N' TO AACTL-SHUTDOWN.
MOVE 'APIMSGS ' TO AACTL-MSG-DDN.
CALL EAC-ENDEVOR-APINAME USING AACTL AUSCL-RQ.
MOVE AACTL-RTNCODE TO WS-RETURN-CODE.
INITIALIZE AACTL-DATAAREA.
MOVE 'Y' TO AACTL-SHUTDOWN.
MOVE 'APIMSGS ' TO AACTL-MSG-DDN.
CALL EAC-ENDEVOR-APINAME USING AACTL.
CLOSE INPUT-FILE.
MOVE WS-RETURN-CODE TO RETURN-CODE.
GOBACK.
Sample JCLTest the KGAPISCL COBOL program
//KGRIMES JOB (12345,00,P),'KEVIN GRIMES',REGION=0M,
// CLASS=Q,MSGCLASS=X,NOTIFY=&SYSUID
//*
//STEP01 EXEC PGM=NDVRC1,REGION=4M,
// PARM='CONCALL,DDN:APILIB,KGAPISCL,E'
//APILIB DD DISP=SHR,DSN=KGRIMES.PDS.LOADLIB
//C1MSGS1 DD SYSOUT=*
//C1MSGS2 DD SYSOUT=*
//SYMDUMP DD DUMMY
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//C1PRINT DD SYSOUT=*
//APIMSGS DD SYSOUT=*
//APISCLIN DD *
SET STOPRC 16 .
RETRIEVE ELEMENT 'KGCOPY05'
FROM ENVIRONMENT 'DEVL'
SYSTEM 'TEST'
SUBSYSTEM 'TEST'
TYPE 'COPY'
STAGE D
TO DDNAME 'ELMOUT'
OPTION
CCID 'KEVIN'
COMMENT 'TESTING ENDEVOR API PROGRAM'
OVERRIDE SIGNOUT
SEARCH
.
EOF.
//ELMOUT DD DISP=SHR,DSN=KGRIMES.PDS.SOURCE(KGCOPY05)
//APIMSGS DD SYSOUT=*
//*
RXSCL - Rexx FunctionA Rexx function that calls the KGAPISCL COBOL program to execute SCL statements
/* REXX -- RXSCL - ENDEVOR API SCL FUNCTION */
X = MSG(OFF)
"ALLOC FI(C1MSGS1) SYSOUT(X)"
"ALLOC FI(C1MSGS2) SYSOUT(X)"
"ALLOC FI(SYMDUMP) DUMMY REUSE"
"ALLOC FI(SYSUDUMP) DUMMY REUSE"
"ALLOC FI(SYSPRINT) SYSOUT(X)"
"ALLOC FI(SYSOUT) SYSOUT(X)"
"ALLOC FI(C1PRINT) SYSOUT(X)"
"ALLOC FI(APILIB) DA('@KGRI.PDS.LOADLIB') SHR"
"ALLOC FI(APIMSGS) SYSOUT(X)"
"ALLOC FI(BSTERR) SYSOUT(X)"
"ALLOC F(APISCLIN) DSORG(PS) TRACKS SPACE(5,5)" ,
"LRECL(80) BLKSIZE(3120) RECFM(F,B) UNIT(SYSDA) NEW "
X = MSG(ON)
PULL QCOUNT
"EXECIO" QCOUNT "DISKW APISCLIN ( FINIS"
"CALL *(CONCALL) 'DDN:APILIB,KGAPISCL,E' ";
X = MSG(OFF)
"FREE FI(APISCLIN)"
"FREE FI(C1MSGS1)"
"FREE FI(C1MSGS2)"
"FREE FI(SYMDUMP)"
"FREE FI(SYSUDUMP)"
"FREE FI(SYSPRINT)"
"FREE FI(SYSOUT)"
"FREE FI(C1PRINT)"
"FREE FI(APILIB)"
"FREE FI(APIMSGS)"
"FREE FI(BSTERR)"
X = MSG(ON)
EXIT 0
RXTEST1 - Rexx Application
Calls the RXSCL Rexx function to execute Endevor SCL statements
/* REXX -- RXTEST1 */
/*------------------------------------------------------------*/
/* Call Endevor SCL API FUNCTION */
/*------------------------------------------------------------*/
QUEUE " SET STOPRC 16 . "
QUEUE " RETRIEVE ELEMENT 'KGCOPY05' "
QUEUE " FROM ENVIRONMENT 'DEVL' "
QUEUE " SYSTEM 'TEST' "
QUEUE " SUBSYSTEM 'TEST' "
QUEUE " TYPE 'COPY' "
QUEUE " STAGE D "
QUEUE " TO DDNAME 'ELMOUT' "
QUEUE " OPTION "
QUEUE " CCID 'KEVIN ' "
QUEUE " COMMENT 'TESTING ENDEVOR API PROGRAM' "
QUEUE " . "
QUEUE " EOF. ”
QCOUNT = QUEUED()
PUSH QCOUNT
DSN = 'KGRIMES.PDS.SOURCE(KGCOPY05)'
"ALLOC F(ELMOUT) DA('"DSN"') SHR REUS"
API_RC = RXSCL()
"FREE FI(ELMOUT)"
EXIT API_RC
ENTBJAPI Sample ProgramSample Inventory List Function Call
RXLSBS - List Endevor Subsystems
A Rexx Function that calls the sample ENTBJAPI program to get a list of Endevor subsystems and writes them to the stack
/* REXX */
/*****************************************************************/
/* */
/* NAME: RXLSBS */
/* */
/* FUNCTION: */
/* */
/* This Rexx function calls the Endevor sample API program to */
/* get a list of all subsystems for the specified SYSTEM. */
/* */
/****************************************************************/
X = MSG(OFF)
ARG ENVIR,STAGE,SYSTEM
IF STAGE = '' THEN STAGE = '*'
IF SYSTEM = '' THEN SYSTEM = '*’
ENVIR = LEFT(ENVIR,8)
STAGE = LEFT(STAGE,1)
SYSTEM = LEFT(SYSTEM,8)
"ALLOC FI(SYMDUMP) DUMMY REUSE"
"ALLOC FI(SYSUDUMP) DUMMY REUSE"
"ALLOC FI(SYSOUT) SYSOUT(X)"
"ALLOC FI(SYSPRINT) SYSOUT(X)"
"ALLOC FI(BSTERR) SYSOUT(X)"
"ALLOC FI(BSTAPI) SYSOUT(X)”
"ALLOC F(SYSIN) DSORG(PS) TRACKS SPACE(5,5)" ,
"LRECL(80) BLKSIZE(3120) RECFM(F,B) UNIT(SYSDA) NEW "
"ALLOC F(MSG3FILE) DSORG(PS) TRACKS SPACE(5,5)" ,
"LRECL(133) BLKSIZE(0) RECFM(F,B) UNIT(SYSDA) NEW "
"ALLOC F(EXT1ELM) DSORG(PS) TRACKS SPACE(5,5)" ,
"LRECL(2048) BLKSIZE(0) RECFM(V,B) UNIT(SYSDA) NEW ”
X = MSG(ON)
QUEUE 'AACTL MSG3FILEEXT1ELM '
QUEUE 'ALSBS AN 'ENVIR || STAGE || SYSTEM
QUEUE 'RUN '
QUEUE 'AACTLY '
QUEUE 'RUN '
QUEUE 'QUIT '
"EXECIO 6 DISKW SYSIN ( FINIS"
"CALL *(NDVRC1) 'ENTBJAPI' ";
API_RC = RC
"EXECIO * DISKR MSG3FILE (FINIS STEM MSG3FILE."
"EXECIO * DISKR EXT1ELM (FINIS STEM LSBS.”
X = MSG(OFF)
"FREE FI(SYSIN)"
"FREE FI(MSG3FILE)”
"FREE FI(EXT1ELM)"
"FREE FI(SYMDUMP)"
"FREE FI(SYSUDUMP)"
"FREE FI(SYSPRINT)"
"FREE FI(SYSOUT)"
"FREE FI(BSTERR)"
"FREE FI(BSTAPI)"
X = MSG(ON)
IF API_RC > 0 THEN
DO
DO I = 1 TO MSG3FILE.0
SAY MSG3FILE.I
END
RETURN API_RC
END
DO I = 1 TO LSBS.0
QUEUE LSBS.I
END
PUSH LSBS.0
RETURN 0
RXTEST2 - Rexx Application
Call RXLSBS Rexx function to get a list of Endevor Subsystems
/* REXX -- RXTEST */
/*------------------------------------------------------------*/
/* Get Subsystem List */
/*------------------------------------------------------------*/
RQ_ENV = 'MVSPROD'
RQ_STG_ID = 'P'
RQ_SYSTEM = 'FINANCE'
RC = RXLSBS(RQ_ENV,RQ_STG_ID,RQ_SYSTEM)
IF RC ¬= 0 THEN
DO
SAY 'RXTEST RC =' RC
EXIT RC
END
PULL LSBS_REC_CNT
DO I = 1 TO LSBS_REC_CNT
PULL LSBSREC
CALL PARSE_LSBS_REC
SAY 'ENV:' ALSBS_RS_ENV,
'SYSTEM:' ALSBS_RS_SYSTEM,
'SUBSYS:' ALSBS_RS_SUBSYS
END
EXIT
/*------------------------------------------------------------*/
/* Parse the LSBS record into variables */
/*------------------------------------------------------------*/
PARSE_LSBS_REC:
ALSBS_RS_SITE = SUBSTR(LSBSREC,13,1)
ALSBS_RS_ENV = SUBSTR(LSBSREC,14,8)
ALSBS_RS_SYSTEM = SUBSTR(LSBSREC,22,8)
ALSBS_RS_SUBSYS = SUBSTR(LSBSREC,30,8)
ALSBS_RS_STG_NAME = SUBSTR(LSBSREC,38,8)
ALSBS_RS_STG_ID = SUBSTR(LSBSREC,46,1)
ALSBS_RS_STG_REL = SUBSTR(LSBSREC,47,4)
ALSBS_RS_UPD_CNT = SUBSTR(LSBSREC,51,8)
ALSBS_RS_UPD_DATE = SUBSTR(LSBSREC,59,8)
ALSBS_RS_UPD_TIME = SUBSTR(LSBSREC,67,8)
ALSBS_RS_UPD_USER = SUBSTR(LSBSREC,75,8)
ALSBS_RS_TITLE = SUBSTR(LSBSREC,83,50)
ALSBS_RS_NXT_SBS = SUBSTR(LSBSREC,133,8)
ALSBS_RS_FMID = SUBSTR(LSBSREC,141,5)
ALSBS_RS_PREGEXC = SUBSTR(LSBSREC,149,1)
RETURN
Kevin Grimes, PresidentCA Endevor Global User Community
https://communities.ca.com/web/kevin_grimes/myca