Endevor API An Introduction to the Endevor Application

Endevor API An Introduction to the Endevor Application Programming Interface Kevin Grimes, President CA Endevor Global User Community

Agenda 1) What good is the API? 2) Architecture 3) Some Examples

1 What Good is 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: • • • CCIDRPT 1 ENHAAPGM ENHAEPGM ENHAPLST ENHAPUPD Load Module Only: • ENTBJAPI

3 Examples

SCL API Function The 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 SUB 1 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 05 LS-SCL-TYPE PIC 9(4) COMP. PIC X.

PROCEDURE DIVISION USING LS-PARM. MAIN-LINE. INITIALIZE AUSCL-RQ-DATAAREA. MOVE LS-SCL-TYPE TO AUSCL-RQ-SCLTYPE. OPEN 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 SUB 1 MOVE WS-INPUT-RECORD TO AUSCL-RQ-SCL(SUB 1) 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 JCL Test the KGAPISCL COBOL program

//KGRIMES JOB (12345, 00, P), 'KEVIN GRIMES', REGION=0 M, // CLASS=Q, MSGCLASS=X, NOTIFY=&SYSUID //* //STEP 01 EXEC PGM=NDVRC 1, REGION=4 M, // PARM='CONCALL, DDN: APILIB, KGAPISCL, E' //APILIB DD DISP=SHR, DSN=KGRIMES. PDS. LOADLIB //C 1 MSGS 1 DD SYSOUT=* //C 1 MSGS 2 DD SYSOUT=* //SYMDUMP DD DUMMY //SYSUDUMP DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //C 1 PRINT DD SYSOUT=* //APIMSGS DD SYSOUT=* //APISCLIN DD * SET STOPRC 16. RETRIEVE ELEMENT 'KGCOPY 05' 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 //APIMSGS //* DD DISP=SHR, DSN=KGRIMES. PDS. SOURCE(KGCOPY 05) DD SYSOUT=*

RXSCL - Rexx Function A Rexx function that calls the KGAPISCL COBOL program to execute SCL statements

/* REXX -- RXSCL - ENDEVOR API SCL FUNCTION */ X = MSG(OFF) "ALLOC "ALLOC "ALLOC FI(C 1 MSGS 1) SYSOUT(X)" FI(C 1 MSGS 2) SYSOUT(X)" FI(SYMDUMP) DUMMY REUSE" FI(SYSUDUMP) DUMMY REUSE" FI(SYSPRINT) SYSOUT(X)" FI(SYSOUT) SYSOUT(X)" FI(C 1 PRINT) SYSOUT(X)" FI(APILIB) DA('@KGRI. PDS. LOADLIB') SHR" FI(APIMSGS) SYSOUT(X)" 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(C 1 MSGS 1)" "FREE FI(C 1 MSGS 2)" "FREE FI(SYMDUMP)" "FREE FI(SYSUDUMP)" "FREE FI(SYSPRINT)" "FREE FI(SYSOUT)" "FREE FI(C 1 PRINT)" "FREE FI(APILIB)" "FREE FI(APIMSGS)" "FREE FI(BSTERR)" X = MSG(ON) EXIT 0

RXTEST 1 - Rexx Application Calls the RXSCL Rexx function to execute Endevor SCL statements

/* REXX -- RXTEST 1 */ /*------------------------------*/ /* Call Endevor SCL API FUNCTION */ /*------------------------------*/ QUEUE QUEUE QUEUE QUEUE " " " " SET STOPRC 16. RETRIEVE ELEMENT 'KGCOPY 05' FROM ENVIRONMENT 'DEVL' SYSTEM 'TEST' SUBSYSTEM 'TEST' TYPE 'COPY' STAGE D TO DDNAME 'ELMOUT' OPTION CCID 'KEVIN ' COMMENT 'TESTING ENDEVOR API PROGRAM'. EOF. " " " ”

QCOUNT = QUEUED() PUSH QCOUNT DSN = 'KGRIMES. PDS. SOURCE(KGCOPY 05)' "ALLOC F(ELMOUT) DA('"DSN"') SHR REUS" API_RC = RXSCL() "FREE FI(ELMOUT)" EXIT API_RC

ENTBJAPI Sample Program Sample 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 IF SYSTEM = '' THEN STAGE = '' THEN SYSTEM = '*' = '*’

ENVIR = LEFT(ENVIR, 8) STAGE = LEFT(STAGE, 1) SYSTEM = LEFT(SYSTEM, 8) "ALLOC "ALLOC FI(SYMDUMP) DUMMY REUSE" FI(SYSUDUMP) DUMMY REUSE" FI(SYSOUT) SYSOUT(X)" FI(SYSPRINT) SYSOUT(X)" FI(BSTERR) SYSOUT(X)" 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(MSG 3 FILE) DSORG(PS) TRACKS SPACE(5, 5)" , "LRECL(133) BLKSIZE(0) RECFM(F, B) UNIT(SYSDA) NEW " "ALLOC F(EXT 1 ELM) DSORG(PS) TRACKS SPACE(5, 5)" , "LRECL(2048) BLKSIZE(0) RECFM(V, B) UNIT(SYSDA) NEW ”

X = MSG(ON) QUEUE QUEUE 'AACTL MSG 3 FILEEXT 1 ELM ' 'ALSBS AN 'ENVIR || STAGE || SYSTEM 'RUN ' 'AACTLY ' 'RUN ' 'QUIT ' "EXECIO 6 DISKW SYSIN ( FINIS" "CALL *(NDVRC 1) 'ENTBJAPI' "; API_RC = RC "EXECIO * DISKR MSG 3 FILE (FINIS STEM MSG 3 FILE. " "EXECIO * DISKR EXT 1 ELM (FINIS STEM LSBS. ” X = MSG(OFF) "FREE FI(SYSIN)" "FREE FI(MSG 3 FILE)”

"FREE FI(EXT 1 ELM)" "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 MSG 3 FILE. 0 SAY MSG 3 FILE. I END RETURN API_RC END DO I = 1 TO LSBS. 0 QUEUE LSBS. I END

PUSH LSBS. 0 RETURN 0

RXTEST 2 - 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 ALSBS_RS_ENV ALSBS_RS_SYSTEM = SUBSTR(LSBSREC, 13, 1) = SUBSTR(LSBSREC, 14, 8) = SUBSTR(LSBSREC, 22, 8)

ALSBS_RS_SUBSYS ALSBS_RS_STG_NAME ALSBS_RS_STG_ID ALSBS_RS_STG_REL ALSBS_RS_UPD_CNT ALSBS_RS_UPD_DATE ALSBS_RS_UPD_TIME ALSBS_RS_UPD_USER ALSBS_RS_TITLE ALSBS_RS_NXT_SBS ALSBS_RS_FMID ALSBS_RS_PREGEXC RETURN = = = SUBSTR(LSBSREC, 30, 8) SUBSTR(LSBSREC, 38, 8) SUBSTR(LSBSREC, 46, 1) SUBSTR(LSBSREC, 47, 4) SUBSTR(LSBSREC, 51, 8) SUBSTR(LSBSREC, 59, 8) SUBSTR(LSBSREC, 67, 8) SUBSTR(LSBSREC, 75, 8) SUBSTR(LSBSREC, 83, 50) SUBSTR(LSBSREC, 133, 8) SUBSTR(LSBSREC, 141, 5) SUBSTR(LSBSREC, 149, 1)

Kevin Grimes, President CA Endevor Global User Community kevin. grimes@mac. com https: //communities. ca. com/web/kevin_grimes/myca