Checking the availability of the REST server

Sample JCL member RSTCHECK can be used to, in general, check the availability of the REST server and, specifically, check whether a webhook for a specific event id is subscribed to. See the listing of RSTCHECK below for further details:

...

//jobname  JOB (account),'Check REST Server', <=== Change Accordingly 
//             CLASS=?,NOTIFY=?,               <=== Change Accordingly 
//             MSGCLASS=?                      <=== Change Accordingly 
//******************************************************************** 
//* 
//* This job tests the connection to the REST server in general and,
//* specifically, whether a particular event is active (i.e. is 
//* subscribed to). 
//* 
//* The operation is traced (in case there are problems to resolve) 
//* and the trace output is written to the HTPTRACE ddname. 
//* 
//* <your.server.address> and <its port> must be replaced with values 
//* for your particular implementation. 
//* 
//* The supplied JCL tests whether the skel notified event id 52 is 
//* active, but you can test of any event id you wish by changing 
//* the number. 
//* 
//* Replacing skel in the URN by hllx or log will test whether 
//* hllx or log notified events are active, i.e. one of 
//* 
//* URN=/zmfrest/query/skel/52 
//* URN=/zmfrest/query/hllx/52 
//* URN=/zmfrest/query/log/52 
//*
// * You can test whether an event is subcribed to for a specific 
// * application by adding the appl as a filter, e.g. 
// * 
// * URN=/zmfrest/query/skel/52?appl=DEMO 
// * 
// ******************************************************************** 

//JOBLIB   DD  DISP=SHR,DSN=somnode.CMNZMF.LOAD 
//         DD  DISP=SHR,DSN=somnode.SERCOMC.LOAD 
//* 
//* 
//DELTRACE EXEC PGM=IEFBR14 
//DD1       DD DISP=(MOD,DELETE),UNIT=SYSDA,SPACE=(TRK,0), 
//             DSN=yourhlq.HTTP.TRACE.OUTPUT 
//* 
//TSTEVSRV EXEC PGM=CMNURIBA,REGION=0M 
//* 
//SYSPRINT  DD SYSOUT=* 
//SYSUDUMP  DD SYSOUT=* 
//HTPTRACE  DD DISP=(,CATLG),DSN=yourhlq.HTTP.TRACE.OUTPUT, 
//             UNIT=SYSDA,SPACE=(CYL,(1,10),RLSE), 
//             DCB=(RECFM=V,LRECL=1028,BLKSIZE=0) 
//SYSIN     DD * 
Server=<your.server.address> 
Port=<its port> 
Context=<event servlet context, default is zmfevent> 
Trace=YES 
Method=GET 
URN=/zmfevent/query/skel/52

The following shows the same job steps with specific values. Note that if the REST server is available and the specific event id is subscribed to then the job will receive a 200 http code from the server and the step will end with cc=0. If the event id is not subscribed to then http code 418 will be received and the job step will end with cc=12. If the event server cannot be contacted then some other http code may be presented and further information in the trace dataset may be of use.

...

//*
//DELTRACE EXEC PGM=IEFBR14 
//DD1       DD DISP=(MOD,DELETE),UNIT=SYSDA,SPACE=(TRK,0),
//             DSN=WSER58.HTTP.TEMP.OUTPUT 
/* 
//* 
//TSTEVSRV EXEC PGM=CMNURIBA,REGION=0M 
//* 
//SYSPRINT  DD SYSOUT=*
//SYSUDUMP  DD SYSOUT=*
//HTPTRACE  DD DISP=(,CATLG),DSN=WSER58.HTTP.TEMP.OUTPUT,
//             UNIT=SYSDA,SPACE=(CYL,(1,10),RLSE),
//             DCB=(RECFM=V,LRECL=1028,BLKSIZE=0)
//SYSIN     DD *
Server=d001.microfocus.com
Port=09992
Trace=YES
Method=GET
URN=/zmfevent/query/skel/52

Formatting JSON responses from the REST server

Any response from the REST server is, by default, echoed in SYSPRINT via 100 byte wrapped-around output. Normally you may not be interested in anything other than the return code from the REST server. However, in some circumstances you may have invoked a process that returns a result set/messages that you wish to keep as part of, for example, the build output for a component.

If the response is supplied as JSON then we can use the IBM supplied 'pretty print' mechanism (SYS1.SAMPLIB(HWTJSPRT)) to format the JSON into something more readable. To do this you need only add a CMNRSPNS dd statement to the CMNURIBA step to write the response to a named temporary file and following this with an execution of HWTJSPRT on this named temporary file.

Note that the response is no longer written to SYSPRINT in this case.

An example of doing this for a specific event 100 invocation is shown below, the extra JCL statements are the CMNRSPNS DD statement in the EVENT100 step and the whole of the PRETTY step.

...

//* 
//* Call the REST server for ZMF event number 100 
//* 
//EVENT100 EXEC PGM=CMNURIBA 
//* 
//SYSPRINT  DD SYSOUT=* 
//SYSUDUMP  DD SYSOUT=* 
//CMNRSPNS  DD DISP=(,CATLG),DSN=WSER58.JSON.TEMPOUT, 
//             SPACE=(CYL,(1,1)),UNIT=SYSDA 
//JSONIN   DD  DATA,DLM=@@ 
{  
    "EVENT"         : "100",  
    "USERID"        : "WSER58", 
    "APPL"          : "ZSRV", 
    "PACKAGE"       : "ZSRV000007", 
    "SITE"          : "",
    "RELEASE"       : "",
    "RELEASEAREA"   : "",
    "PROMOTIONNAME" : "D002DEV",
    "PROMOTIONLEVEL": "10",
    "LIBTYPE"       : "JAV",
    "COMPONENT"     : "com/serena/sercmn/zmf/constants/IAccessTypes.java" 
} 
@@ 
//SYSIN    DD  * 
Server=d001.microfocus.com 
Port=09992 
Context=zmfevent 
Method=POST 
/* 
//* 
// PRETTY   EXEC PGM=IKJEFT01,REGION=0M 
// REMOVE    DD DISP=(OLD,DELETE),DSN=WSER58.JSON.TEMPOUT 
// SYSEXEC   DD  DISP=SHR,DSN=SYS1.SAMPLIB 
// SYSTSPRT  DD DISP=(,PASS),DSN=&&LIST05, 
// UNIT=SYSALLDA,SPACE=(CYL,(1,5),RLSE), 
// DCB=(RECFM=FBA,LRECL=133,BLKSIZE=27930) 
// SYSTSIN   DD  * 
HWTJSPRT WSER58.JSON.TEMPOUT