The DFHWOSM macros invoke the CICS® module DFHWOS to provide services to the overseer program. The macros are the supported interface to the CAVM data sets, and are supplied to perform the following functions:
The macros are described in detail in the following sections. For all the DFHWOSM macros, the following rules apply:
When DFHWOS first invokes the overseer program, it passes a value in register 1 which is known as the ENTRY token. The ENTRY token value is stored by the overseer program on entry and is passed back to DFHWOS as input to the BUILD, OSCMD, JJS, and JJC macros.
The DFHWOSM FUNC=BUILD macro must be the first macro issued by the overseer program and must complete successfully. The register 1 output from this macro is a second token called the BUILD token. The BUILD token value is stored by the overseer program and passed back to DFHWOS as input to the OPEN, CLOSE, READ, QJJS, and TERM macros.
The DFHWOSM FUNC=BUILD macro must be issued by the overseer program to initialize its communication with DFHWOS. No other macro can be issued by the overseer program until DFHWOS FUNC=BUILD has completed successfully.
label DFHWOSM FUNC=BUILD
[,TOKEN={token register|14}]
The DFHWOSM FUNC=CLOSE macro terminates access to the CAVM data sets for a named generic applid.
label DFHWOSM FUNC=CLOSE
[,PARM={parm address|1}]
[,TOKEN={token register|14}]
The TOKEN value is the BUILD token.
The DFHWOSM FUNC=DSECT macro generates a number of DSECTs, including the DSECT of the DBLID definitions.
DFHWOSM FUNC=DSECT
The DFHWOSM FUNC=JJC macro issues a JES cancel for a named job with a JES job identifier.
DFHWOSM FUNC=JJC
[,PARM={parm address|1}]
[,TOKEN={token register|14}]
The TOKEN value is the ENTRY token.
Supplied with a job name and JES job identifier, both versions of the DFHWOSM FUNC={JJS|QJJS} macro return the current JES job status into a copy of the JES subsystem options block (SSOB).
The FUNC=JJS macro returns control when the JES call has completed successfully or unsuccessfully. The FUNC=QJJS macro returns control immediately and posts an event control block (ECB) once the JES request has completed.
label DFHWOSM FUNC={JJS|QJJS}
[,PARM={parm address|1}]
[,TOKEN={token register|14}]
The TOKEN value is the ENTRY token.
For FUNC=QJJS, the PARM value is a pointer to the addresses of the following:
The FUNC=QJJS macro requires 2 ECBs: the first is posted when the JES call completes; the second is posted if a time-out occurs before JES returns.
The TOKEN value is the BUILD token.
The DFHWOSM FUNC=OPEN macro initializes access to the CAVM data sets for a named generic applid.
label DFHWOSM FUNC=OPEN
[,PARM={parm address|1}]
[,TOKEN={token register|14}]
The TOKEN value is the BUILD token.
A register 15 return code value of ‘0’ through ‘5’ indicates that a DFHWOSM FUNC=READ macro can now be issued. A return code value of ‘6’ or above indicates that the OPEN has failed and that the overseer program will not be able to access the CAVM data sets.
The DFHWOSM FUNC=OSCMD macro is used to issue MVS commands. (The overseer program restarts a failed region in place by issuing this macro.) The text of the required MVS command is provided as input to the macro, and the OSCMD service issues an SVC 34 specifying this command text. In addition, the OSCMD service issues an MVS WTO request so that a copy of the command text appears on the MVS console to keep the operator informed of what is about to happen. This copy has the comment ‘(BY IOP)’ appended to show that the command is going to be issued by an overseer program. A second copy of the command text is sent to the console when the MVS command is issued.
label DFHWOSM FUNC=OSCMD
[,PARM={parm address|1}]
[,TOKEN={token register|14}]
The TOKEN value is the ENTRY token.
The DFHWOSM FUNC=READ macro returns information about a named generic applid from its associated CAVM data sets.
label DFHWOSM FUNC=READ
[,PARM={parm address|1}]
[,TOKEN={token register|14}]
In the first two bytes of the second word of each of these doublewords you supply the DBLID of the information you require. Each piece of information that you can request is identified by a DBLID, and a list of these is provided in Figure 56.
The first word of each doubleword is an output area to contain the address of the requested information, and the last two bytes of the second word of each doubleword contain the length of the information. The end of the dbllist is signaled by setting the high-order bit of the last doubleword to ‘1’. Figure 55 illustrates the input to and output from the READ macro.
The TOKEN value is the BUILD token.
DBLIDs for the active:
DBLID1 EQU X'0001' JOB NAME
DBLID2 EQU X'0002' JES JOB ID
DBLID3 EQU X'0003' JOB SUBMISSION TIME (STIME)
DBLID4 EQU X'0004' JOB STEP TASK ATTACH TIME (ATIME)
DBLID5 EQU X'0005' CANCEL NAME
DBLID6 EQU X'0006' JES SSNAME
DBLID7 EQU X'0007' MVS SMF NAME
DBLID8 EQU X'0008' MVS IPL TIME
DBLID9 EQU X'0009' SPECIFIC APPL NAME
DBLID10 EQU X'000A' ADDRESS SPACE IDENTIFIER (ASID)
DBLID11 EQU X'000B' RESTART TYPE
DBLID12 EQU X'000C' - X'001F' SPARE FOR STATE CTL ITEMS
DBLID32 EQU X'0020' HEARTBEAT INTERVAL
DBLID33 EQU X'0021' HEARTBEAT COUNTER
DBLID34 EQU X'0022' MSG FILE CURSOR
DBLID35 EQU X'0023' STATUS VALUE (STATE)
DBLID36 EQU X'0024' INQUIRE HEALTH DATA
DBLID37 EQU X'0025' INQUIRE GLOBAL DATA
DBLID38 EQU X'0026' SYSPLEX NAME
DBLID39 EQU X'0027' MVS SYSTEM NAME
DBLID40 EQU X'0028' MVS SYSTEM TOKEN
DBLIDs for the alternate:
DBLID257 EQU X'0101' JOB NAME
DBLID258 EQU X'0102' JES JOB ID
DBLID259 EQU X'0103' JOB SUBMISSION TIME (STIME)
DBLID260 EQU X'0104' JOB STEP TASK ATTACH TIME (ATIME)
DBLID261 EQU X'0105' CANCEL NAME
DBLID262 EQU X'0106' JES SSNAME
DBLID263 EQU X'0107' MVS SMF NAME
DBLID264 EQU X'0108' MVS IPL TIME
DBLID265 EQU X'0109' SPECIFIC APPL NAME
DBLID266 EQU X'010A' ADDRESS SPACE IDENTIFIER (ASID)
DBLID267 EQU X'010B' RESTART TYPE
DBLID268 EQU X'010C' - X'011F' SPARE FOR STATE CTL ITEMS
DBLID288 EQU X'0120' HEARTBEAT INTERVAL
DBLID289 EQU X'0121' HEARTBEAT COUNTER
DBLID290 EQU X'0122' MSG FILE CURSOR
DBLID291 EQU X'0123' STATUS VALUE (STATE)
DBLID292 EQU X'0124' INQUIRE HEALTH DATA
DBLID293 EQU X'0125' INQUIRE GLOBAL DATA
DBLID294 EQU X'0126' SYSPLEX NAME
DBLID295 EQU X'0127' MVS SYSTEM NAME
DBLID296 EQU X'0128' MVS SYSTEM TOKEN
If a completion code of ‘0’ through ‘5’ is returned to register 15, each doubleword of the DBLLIST contains the address (4 bytes) and the length (2 bytes) of the output from this read. A completion code of ‘8’, ‘10C’, or ‘1xx’ indicates a READ failure.
If you are using DBCTL and have active and alternate DBCTL subsystems, status information about the subsystem connected to the active CICS is written to the CAVM data sets. However, the supplied sample overseer program does not read the DBCTL information from the CAVM data set. If you want the overseer to retrieve this information and to display or use it, you must write your own overseer program.
The information in the CAVM data set about the connected DBCTL subsystem is updated when the active CICS:
If more than one active CICS is connected to a single DBCTL subsystem, the CAVM data set for each CICS contains information about the same DBCTL subsystem. The overseer can recognize this situation because in every case the DBCTL startup time stamp is the same.
Copy book DFHDXGHD contains the information shown in Figure 57.
DFHDXGHD DSECT
GHDDXADB DS CL4 DBCTL SSID
GHDDXRSE DS CL8 IMS RSE name
GHDDXCTM DS CL4 IMS connect time
GHDDXDTM DS CL4 IMS disconnect time
GHDDXJNM DS CL8 JES Job name of old active IMS
GHDDXJID DS CL8 JES Job ID of old active IMS
GHDDXASD DS H ASID of old active IMS
GHDDXIRT DS X IMS region type
DXRHTSBY EQU X'01' region type is hot standby
DXRDBDC EQU X'02' region type is IMS DB/DC
DXRDBCTL EQU X'04' region type is DBCTL
GHDDXTYP DS X GHD message type
DXMCNNCT EQU X'01' Message type = DBCTL connection
DXMDISC EQU X'02' Message type = DBCTL disconnect
DXMDRAF EQU X'04' Message type = DRA failure
DXMABEND EQU X'08' Message type = DBCTL abend
DXMERROR EQU X'80' Indicates severe error in DFHDBCT
DXGHDLEN EQU *-DFHDXGHD length of CICS XRF/DBCTL GHD
ORG ,
The DFHWOSM FUNC=TERM macro terminates communication between the overseer program and DFHWOS, and releases any associated storage. It must be issued before the overseer program completes to ensure an orderly termination.
label DFHWOSM FUNC=TERM
[,TOKEN={token register|14}]