5. OPERATION › 5.1 Operation Overview › 5.1.6 VCC User Exits › 5.1.6.1 VTOC DSCB Exit (VCCUEXIT)
5.1.6.1 VTOC DSCB Exit (VCCUEXIT)
VCC allows you to extract site-dependent information from the
Format 1 DSCB and to build a user segment in the VCC output
record that is based on this information. Module VCCUEXIT is
called after the record has been built and just before the
VCCWRITR routine is called to write it to SMF or to the
VCCDATA data set. VCCVTOC expects no return codes from the
VCCUEXIT module.
An example of the VCCUEXIT is provided in the library
sharedprefix.MICS.ASM as member VCCAEXIT. The source provided
is in Assembler Language. You may copy VCCAEXIT, modify it to
meet your specifications, assemble and link edit the object
deck as VCCUEXIT.
NOTE: Saving the source code for your modified version of
VCCUEXIT into sharedprefix.MICS.ASM as VCCAEXIT is not
recommended as this member may be updated or replaced by
future maintenance, thus removing your modifications. If you
have made modifications to the source code, copy your updated
member to sharedprefix.LOCALMOD.CNTL and document it.
In the sample code we distribute, VCCUEXIT retrieves a few
bytes from the Format 1 DSCB used by Sterling Software's
DMS/OS and arranges them in a user segment.
For more details regarding linkage conventions, work areas,
and general purpose register usage, see the sample source
member provided in sharedprefix.MICS.ASM(VCCAEXIT).
Review the macro definitions carefully before you start any
coding. If you would like some work space, you can add WORK
field definitions under the DSECT labeled SUSRDSCT. Simply
define work fields after the EQUATE that establishes the
length of the user segment.
Use fields SBASUSRS (user segment offset), SBASUSRL (user
segment length), and SBASUSR# (number of user segments) as
the reference points for the user segment. You must place
the user segment at the end of the VCC record, and update the
VCC record RDW (SBASRDW) with the user segment length that is
being added to the value that is already in SBASRDW. Make
sure that fields SBASUSRS, SBASUSRL, and SBASUSR# are set
properly when adding a user segment as invalid results may
cause VCC and/or VCA to fail. Do not update the VCCRCORD
macro to reflect the user segment field definition layout;
rather, create your own DSECT in the VCCUEXIT module. This
ensures that any maintenance to VCC will not conflict with
the user segment definition. For more information regarding
the VCC record layout, see section 5.2.
After user information has been picked up from the Format 1
DSCB (or elsewhere), you should return control to VCCVTOC
using normal OS return logic as shown in the sample provided.
Module VCCVTOC will then write the SMF record with the user
segment added on to it.
Note the following:
o Do not modify existing fields within the VTCWA area
mapped by the VCCVTCWA MACRO. This could cause a VCC
failure.
o The Format 4 DSCB is kept in the VTCWA DSECT in field
VTCWDSCB. It is 140 bytes in length.
o Certain fields in the base segment are not available
to the VCCUEXIT module because they are filled in by
the common VCCWRITR module. Therefore, do not attempt
to use the following fields in the VCCUEXIT:
SBASTYPE, SBASTIME, SBASDATE, SBASYSID, SBASLEN,
SBASPSTR, SBASVID, SBASVERS.
o Specifying USEREXIT=Y at execution time in VCCPARMS
for the Base VCC Collection process triggers the
LOADing of a load-module called VCCUEXIT.
o You must code VCCUEXIT as reentrant and link-edit it
as RENT,REUS because each concurrently executing
VCCVTOC subtask calls this exit.
o Because VCC runs "authorized", this exit obtains
information from protected areas by issuing the
MODESET macro. If the protection key is set to zero,
make sure that it is reset to nonzero (NZERO) before
control is returned to VCCVTOC.
o The Sample source distributed has been tested and
works successfully in a DMS/OS Release 1.8.1
environment using Sterling defaults. For other
releases of DMS/OS, review the source code and
appropriate Sterling documentation carefully.
