The DFHWOSM macros

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:

DFHWOSM FUNC=BUILD
Open communication with DFHWOS
DFHWOSM FUNC=CLOSE
Terminate access to the CAVM data sets for a named generic applid
DFHWOSM FUNC=DSECT
Generate required DSECTs
DFHWOSM FUNC=JJC
Issue a JES cancel for a named job
DFHWOSM FUNC={JJS|QJJS}
Discover current JES JOB status
DFHWOSM FUNC=OPEN
Initialize access to the CAVM data sets for a named generic applid
DFHWOSM FUNC=OSCMD
Issue MVS™ commands
DFHWOSM FUNC=READ
Retrieve status information for a named generic applid from the CAVM data sets
DFHWOSM FUNC=TERM
Close communication with DFHWOS.

The macros are described in detail in the following sections. For all the DFHWOSM macros, the following rules apply:

The DFHWOSM tokens

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.

DFHWOSM FUNC=BUILD macro

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}]
Input
The TOKEN value is the ENTRY token that was passed to the sample overseer program when it was first invoked by DFHWOS.
Output
Register 1
Contains the BUILD token value, which must be returned as an input value by the overseer program on certain subsequent requests. This value is returned to register 1 only if register 15 has a return code of ‘0’.
Register 15
Contains one of the following completion codes:
0
Communication successfully initialized between the overseer program and DFHWOS
4
Incorrect TOKEN value supplied
8
Insufficient storage.

DFHWOSM FUNC=CLOSE macro

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}]
Input
The PARM value is a pointer to the address of the generic applid whose associated CAVM data sets are no longer to be accessed by the overseer program.

The TOKEN value is the BUILD token.

Output
Register 15
Completion codes:
0
CLOSE request was successful and the CAVM data sets associated with this generic applid can no longer be accessed by the overseer program.
4
Incorrect TOKEN value supplied.
8
Access to CAVM data sets for the named generic applid had not been initialized.

DFHWOSM FUNC=DSECT macro

The DFHWOSM FUNC=DSECT macro generates a number of DSECTs, including the DSECT of the DBLID definitions.

DFHWOSM FUNC=DSECT

DFHWOSM FUNC=JJC macro

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}]
Input
The PARM value is a pointer to the addresses of the following:

The TOKEN value is the ENTRY token.

Output
Register 15
Contains the following completion codes:
0
JES cancel completed; SSOB and status array returned from JES
Nonzero
Return code from JES.

DFHWOSM FUNC={JJS|QJJS} macro

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}]
Input
For FUNC=JJS, the PARM value is a pointer to the addresses of the following:

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.

Output
Register 15
Contains the following completion codes:
0
JES status returned as requested in the SSOB return area
Nonzero
Return code from JES.

DFHWOSM FUNC=OPEN macro

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}]
Input
The PARM value is a pointer to three further addresses, and these are:
  1. The address of the generic applid
  2. The address of the ddname of the control data set
  3. The address of the ddname of the message data set.

The TOKEN value is the BUILD token.

Output
Register 15
Contains one of the following completion codes:
0
Access initialized, active and alternate signed on
1
Access initialized, active signed on
2
Access initialized, alternate signed on
3
Access initialized, nothing signed on
4
Same SMF MVS name; IPL time of active earlier than MVS IPL time
5
Same SMF MVS name; IPL time of alternate earlier than MVS IPL time
6
Insufficient storage
7
Generic applid is not associated with the named CAVM data sets
8
Access already initialized for this generic applid or for this ddname
9
Version numbers of the named CAVM data sets do not match
C
Data set open failure
10
SHOWCB failure.

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.

DFHWOSM FUNC=OSCMD macro

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}]
Input
The PARM value is a single address that points to a "command area". The command area is made up of a 4-byte length field followed by the command data. The length field contains the length of the whole command area. The command data must be in write-to-operator (WTO) command format.

The TOKEN value is the ENTRY token.

Output
Register 0
Completion code set by SVC 34 as a response to the MVS command that was issued by the macro.
Register 15
Response to the macro itself. A return code of ‘16’ indicates that the OSCMD has failed.

DFHWOSM FUNC=READ macro

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}]
Input
The PARM value is a pointer to a parameter list that contains the addresses of the generic applid and the "dbllist". The dbllist is a list of one or more doublewords.

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.

Figure 55. Input to and output from the DFHWOSM FUNC=READ macro
 The picture shows the input to and output from the DFHWOSM FUNC=READ macro, as described in the preceding paragraphs. The parameter list pointer points to a parameter list consisting of two fields--the address of the generic applid, and the address of the "dbllist". The dbllist is shown as a list of several doublewords. The first two bytes of the second word of each doubleword is an input field containing a DBLID. The first word of each doubleword is an output field containing the address of the information requested by the DBLID. The last two bytes of the second word of each doubleword is an output field containing the length of the returned information.
Figure 56. DBLIDs for the DFHWOSM FUNC=READ macro
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
Notes:
  1. The data structures of the status information pointed to by items X'0024' and X'0124' are provided in DSECT DFHXRHDS of CICSTS31.CICS.SDFHMAC.
  2. The data structures of the status information pointed to by items X'0025' and X'0125' are provided in DSECT DFHXRGDS of CICSTS31.CICS.SDFHMAC.
  3. The data structures of the status information pointed to by items X'000B' and X'010B' are mirrors of the field WSJRST in DSECT WSJDESC within DFHWSMDS.
Output
Register 15
Contains one of the following completion codes:
0
Read successful, active and alternate signed on
1
Read successful, active signed on
2
Read successful, alternate signed on.
3
Read successful, nothing signed on
4
Same SMF MVS name; IPL time of active earlier than MVS IPL time
5
Same SMF MVS name; IPL time of alternate earlier than MVS IPL time
8
CAVM data set access not initialized
10C
DBLID not known
1xx
Read subtask problem.

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.

Reading DBCTL status information from the CAVM data sets

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.

Figure 57. DFHDXGHD copy book
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   ,

DFHWOSM FUNC=TERM macro

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}]
Input
The TOKEN value is the BUILD token.
Output
Register 15
Contains the following completion codes:
0
Communication terminated successfully
Nonzero
Request failed.

Related concepts
The sample XRF overseer program
Related tasks
Customizing the sample XRF overseer program
[[ Contents Previous Page | Next Page Index ]]