endevor api an introduction to the endevor application programming interface

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

kevin.grimes@mac.com

https://communities.ca.com/web/kevin_grimes/myca