|
|
 |
Resource for
Troubleshooting PREFERENCE Help Requests
Contents
Information About This Document
What follows is a
Resource for Troubleshooting PREFERENCE Help Requests for SumTotal PREFERENCE
customers. PREFERENCE is a tool for creating and implementing customized help
screens for mainframe environment applications, including CICS and IMS
applications.
The information contained
herein is intended as a central resource to aid PREFERENCE customers in solving
help request problems. In putting this together, we have therefore included
discussions that are both general and specific in focus. Some of the
information can already be found on SumTotal Pathlore Mainframe website under
"Technical Tips and Hints".
While every attempt has
been made to create an accurate and comprehensive document, we understand that
trouble-shooting is at least partially an art. Experience and familiarity is
often the best way that problem solving skills can be developed. Additionally,
it is not our goal to address every possible thing that can go wrong with
PREFERENCE rules. However, we will attempt to provide guidelines for problem
solving as well as specific solutions to specific problems.
Back to Top
General Problem Solving Guidelines
The following is intended to assist our clients in resolving
PREFERENCE help issues. Keep these guidelines in mind as you proceed:
-
Because
different individuals have different skill-sets and authorizations, problem
solving may require a "team" effort, involving a PREFERENCE rules writer, a
PREFERENCE supervisor for getting rules trace, a systems programmer or an
applications programmer. Individuals with previous experience with
PREFERENCE can be especially helpful for solving rules problems.
-
The question
"What has changed?" often leads to the source of a PREFERENCE rules problem.
Has a PREFERENCE upgrade occurred? Have rules been migrated from a
test/development system to production? Have changes occurred
within your application environment?
-
Asking the
question "What is the scope of the problem?" can be helpful in
trouble-shooting help requests. Are all help requests failing or are
problems confined to a single system (such as a test system), or to specific
application screens? Does the problem occur with help processing residing in
a specific PREFERENCE volume? Are problems predictable and easily
recreated or do they seem random?
-
Familiarity
with an overview of the PREFERENCE rules processing "workflow" can ensure
your approach is logical and that you are not missing anything.
-
Familiarity
with the PREFERENCE Trace facility can provide insight into how (and if)
PREFERENCE is internally processing a help request.
-
Contacting
SumTotal technical support for assistance is always an option and
instructions for doing so appear at the bottom of this document. When
contacting technical support, remember that the more information you have
available, the quicker your problem will be resolved. Relevant
information can include screen shots of the application screen, any error
messages, PREFERENCE trace table, as well as information regarding recent
system changes and the scope of the problem (see 3 and 4 above).
Back to Top
Overview of the
PREFERENCE Help Request Process
What follows is a
sequential overview of what happens when a PREFERENCE help request is made.
-
HELP KEY STEP A Help key is detected and processing is passed to the PREFERENCE system
-
INFORMATION PASSING
STEP The
transaction ID, jobname, cursor position (row, col), help key and screen image
of application screen are passed to PREFERENCE. This information is utilized
in the steps that follow.
-
CAPTURE TABLE STEP
The
PREFERENCE Screen Capture table is checked to determine whether the terminal
id is listed for screen capture processing. If the terminal ID is not found in
the Capture table, help request processing will continue.
-
PRODUCT CHECK STEP
If a valid
PREFERENCE expiration code is found, help request processing will continue.
-
TRANSACTION ID STEP PREFERENCE searches for the Transaction ID in the internal rules table.
The search is sequential, volume by volume and in the order displayed on the
Descriptors table within each volume. If the Transaction ID is found, help request
processing will continue.
-
F-KEY
STEP If the
transaction ID is matched, the descriptors table is checked for an F-key
definition. If none has been defined, processing continues for the
current volume. If
an F-key is defined, we check for a match with the F-key passed to
PREFERENCE. If a match occurs, processing continues for the current volume.
-
JOBNAME STEP The Jobname table in the volume where the
transaction ID is detected is checked for any entries. If no Jobname entries
exist, we stay in this volume and proceed. If a Jobname entry or entries exist
and a match occurs, processing continues for the current volume.
-
SCREEN RULE STEP
The Screen
Rules Table attached to the Transaction ID contains character string entries
("phrases") intended to match character strings found on the application
screen. If a match occurs, processing is passed to the associated decision
rule file.
-
DECISION RULES STEP
Decision rules
items and their groups are processed sequentially (All groups (starting with
group 1) in item 2, then all groups in item 3, then all groups in item 4 etc.)
until a data analysis match occurs and processing continues in the index term
step. The data match can be for cursor position or
for field content. If branching is associated with the data analysis match,
then the branch is executed and data analysis starts over at the branch
target.
-
INDEX TERM STEP
In most cases an index term is used to navigate to the help screen. A search is made to find the index term and volume associated with
decision rules match. If the index term is found, the help screen is
presented to the end user.
-
HELP SCREEN DISPLAY
A PREFERENCE item (pointed at by the index term in previous step) is displayed with writer
defined characteristics (menu/no menu, location, hypertext, pick list,
multiple pages, etc.)
-
HELP SCREEN EXIT
F3 exits back
to the application screen. If a pick list is invoked, data from the help
screen is transferred to the application screen at the help request cursor position. If IMS,
F3 exit restores data to application fields using the MOD definition imported
to PREFERENCE.
What follows is an overview of
problems that may occur in the above sequence.
-
HELP KEY STEP
A Help key must be defined for PREFERENCE to detect before any
processing can begin. If a help key is not defined, the help request
will not be presented to PREFERENCE. The PF-Key request will be passed
to and handled by the user's application.
Click here for information on "How to Ensure you have a PF-Key defined for
PREFERENCE Help".
-
INFORMATION PASSING STEP
Key information needed for a help request, such as the transaction ID,
jobname, cursor position (row, col), help key and screen image of application
screen cannot be passed from an application to PREFERENCE if PREFERENCE is
not running. If PREFERENCE is not running, it may be due to an expired
product code.
Click here for information on "How to ensure that your PREFERENCE system
authorization has not expired".
-
CAPTURE
TABLE STEP The PREFERENCE
Screen Capture table is checked to determine whether the terminal id is
listed for screen capture processing. If the terminal ID is found in
the Capture table, help request processing is terminated and the user is
navigated to the location (sign-on frame, supervisor command line, or writer
menu of a volume) specified in the associated entry of the Capture table.
Click here for information on "How to make sure your Help Request is not a
Screen Capture Request".
-
PRODUCT CHECK STEP
If a valid PREFERENCE expiration code is not detected, the help request
is terminated. If the client also has the PHOENIX product and it is
active, the user’s session will be routed to the Sign-on Screen. Click
here for information on "How to ensure that your PREFERENCE system
authorization has not expired".
-
TRANSACTION
ID STEP PREFERENCE searches for the Transaction ID in the internal rules table.
The search is sequential, volume by volume and in the order displayed on the
Descriptors table within each volume. Ordering is important as Transaction IDs
can match on entries using "wild-card" characters within the Descriptors
table. The Transaction ID search is processed only for active volumes. If the
Transaction ID is not found, the help request is routed to the “SIGN-ON FRAME
EDITOR - Bypass error processing” specification. Valid specifications are "E
- Exit to the calling application", "S - go to the PREFERENCE Sign-on Screen"
or "D - produce a PDUMP". The PDUMP will cause a "GD" error message to be
presented to the user.
-
F-KEY STEP
If the transaction ID is
matched, the descriptors table is checked for an F-key definition. If none
has been defined, we stay in this volume and proceed. If an F-key is defined,
we check for a match with the F-key passed to PREFERENCE. If an F-key is
defined but does not match the F-Key passed to PREFERENCE processing returns
to step 5 to search for the next occurrence of the Transaction ID.
-
JOBNAME STEP
If the transaction ID is matched, the Jobname table in the volume where the
transaction ID is detected is checked for any entries. If a Jobname entry or
entries exist, they serve to exclude any other Jobname passed to PREFERENCE.
If no match occurs, the transaction search (step 5) continues.
-
SCREEN RULE STEP
The Screen Rules Table
attached to the Transaction ID contains character string entries ("phrases")
intended to match character strings found on the application screen. If no
screen rule match occurs, the help request is routed to the “SIGN-ON FRAME
EDITOR - Bypass error processing” specification. The valid specifications are
defined above in step 5.
-
DECISION RULES STEP
Decision rules items
and their groups are processed sequentially (All groups (starting with group
1) in item 2, then all groups in item 3, then all groups in item 4 etc.) until
a data analysis match occurs. The match can be for cursor position or for
field content. If no screen rule match occurs, the help request is routed to
the “SIGN-ON FRAME EDITOR - Bypass error processing” specification. The valid
specifications are defined above in step 5.
-
INDEX TERM STEP A
search is made to find the index term and volume associated with decision
rules match. If the index term is not found, a message is presented to the
help-request end user.
-
HELP
SCREEN DISPLAY An incorrect screen display may mean that an
incorrect index term or volume is being used to present the help screen.
Additionally, writer defined characteristics (menu/no menu, location,
hypertext, pick list, multiple pages, etc.) may not be defined correctly.
It is possible that the wrong verbiage has been edited into the help screen.
These situations may occur because your help request is being routed to the
wrong PREFERENCE system. For information on "How to ensure your help
requests are routed to the correct PREFERENCE System", click
CICS or
IMS to choose your environment.
-
HELP
SCREEN EXIT F3 exits back to the
application screen. If a pick list is invoked, data from the help screen is
transferred to the application screen at the help request cursor position. If IMS, F3
exit restores data to application fields using the MOD definition imported to
PREFERENCE. If the MOD definition used is outdated, a corrupted
application screen may appear. To rectify this, the MOD may need to be
re-captured to PREFERENCE.
Back to Top
List of Symptoms and Possible
Causes
Below is a list of common
symptoms indicating that a problem has occurred with a PREFERENCE help request.
Included are causes that may be associated with the
symptoms.
User presses help key and
nothing happens
-
Help-key not defined
-
Application not connected
to PREFERENCE
-
PREFERENCE is not running
-
PREFERENCE authorization
code has expired
-
Help request may be routed
to the wrong PREFERENCE system
-
PREFERENCE Global exit not
enabled
User presses help key and
PREFERENCE sign-on screen is displayed
-
Incorrect entry in Jobname
table in volume containing Transaction ID
-
Incorrect Screen Rules
definition in volume containing Transaction ID
-
Transaction ID not defined
in PREFERENCE
-
Transaction ID is defined
in more than one PREFERENCE volume
-
Transaction ID is defined
in PREFERENCE volume that is not active.
-
Screen Capture Table is
populated and is directing help requests to Sign-on screen
-
Help request may be routed
to the wrong PREFERENCE system
User presses help key and is
navigated to supervisor command line or volume writer menu
-
Screen capture table is
directing help requests to command line or volume writer menu
-
If "RAM FILE IS READ ONLY"
appears at command line, PREFERENCE Trace is turned on and it is attempting to write to a file on
a read-only program file.
-
Help request may be routed
to the wrong PREFERENCE system
User presses help key and
GD024 or other GD error message appears
-
PREFERENCE Terminal ID
characteristics may be incompatible with 3270 Emulator characteristics
-
PREFERENCE internal
processing limit (defined by PROCx= startup parameters) is encountered
-
PREFERENCE programming
error is encountered
User presses help key and
incorrect help screen appears
-
Screen rules may be
written incorrectly
-
Decision rules may be
written incorrectly
-
An invalid version of the
PREFERENCE rules volume may be on the system
-
Application screen has
changed and needs to be recaptured for marked field help
-
Application has changed
and no longer corresponds to decision rules
-
Help request may be routed
to the wrong PREFERENCE system
User presses help key and
partial help screen appears
IMS User presses help key
and receives error condition U4000 ABEND
Exit from help on IMS system
and application screen fields are incorrectly populated
-
MOD definition for IMS
application has changed and is no longer valid (needs to be re-captured)
-
If while
re-capturing the MOD definition you receive a message indicating that the MFS
DSN cannot be found, it means the specified data set name has been misspelled
or the name has been changed.
-
If you re-capture the MOD definition and you receive the same result, then the
wrong MFS DSN for the associated IMS system has been specified for the MOD
capture request. Perform the MOD Capture again specifying the correct
MFS DSN.
Back to Top
Tools for Resolving Rules Problems
-
Click here for instructions on how to use the
Transaction ID Search to determine if a Transaction ID is defined in one
volume, more than one volume, or in no volume within PREFERENCE.
-
Click here for instructions on how to see if
the Capture Table might be directing your help request to the PREFERENCE
sign-on frame
-
Click here for instructions on how to access
and use the PREFERENCE Trace facility
-
Click here for instructions on how to use the
PREFERENCE Run functionality as a tool in resolving rules problems.
-
Click here for instructions on how and when to
use the rbuild command to rebuild the internal PREFERENCE Transaction ID
listing.
Back to Top
Generic Procedure for Help Requests Going to PREFERENCE Sign-on Screen
Outlined below are the
typical "first pass" steps taken by SumTotal to resolve a situation where help
requests are navigated to the PREFERENCE sign-on frame. Whether the problem is
general or confined to a single application screen, begin by focusing on one
application screen and identify the Transaction ID of this screen.
-
Check the Capture table. Access the supervisor Capture
Terminal ID table, remove any entries and try again. Capture
table entries can override help request processing by directing
help requests to the sign-on frame (as well as to the supervisor
command line or to the writer menu of a specified volume).
Click here for information on "How to make
sure your Help Request is not a Screen Capture Request".
-
Invoke the supervisor "rbuild" command. At the supervisor command
line simply type "rbuild" and press ENTER to rebuild the internal PREFERENCE
Transaction ID table. Then try the help request again. When the rbuild process
is complete, you will see a prompt stating "RULES TABLE CONSTRUCTION COMPLETE".
The master rules table lists the Transaction IDs found in all PREFERENCE
volumes, in the sequence that is searched for a match on a help request. This
table is initialized when the PREFERENCE system is brought up, but may require
updating when, for example, GSPCOPY is used to import a volume containing rules
while the system is running.
Click here
for more information on the "RBUILD Command".
-
Verify that
your help requests are being routed to the PREFERENCE system you think it is.
Click here to determine if your CICS Help requests are being
routed to the correct PREFERENCE system.
Click here to determine if your IMS Help requests are being routed to the
correct PREFERENCE system. If you can verify that the PREFERENCE help
system being invoked is correct, then proceed to the next step.
-
Verify that
the Transaction ID is referenced just once within PREFERENCE in an active volume.
Click
here for information on how
to perform a "Transaction ID Search". If a Transaction ID is found more
than once in an active volume or if found in more than one active volume, the
"wrong" Transaction ID entry could be used for rules processing. This
can occur not only in the case of duplicate entries, but also when "wild card"
characters create an unintended match on a Transaction ID. If the
Transaction ID is not found in PREFERENCE, it may be because the transaction
has been misidentified, changed or is misspelled in PREFERENCE. If the
"Transaction ID search" yields a single entry and in one active volume,
continue with the next steps.
-
Identify
the volume being used for rules processing.
Notice if the "ENTER VOLUME" or "ENTER VOLUME OR COURSE" field is populated on
the sign-on frame when help is invoked. A volume name in this field indicates
a Transaction ID match in the volume indicated. If no volume name appears
here,
skip to step 7. Otherwise continue with step 6.
-
Check the
Jobnames Table. Jobnames table entries are designed to exclude processing of help requests
from any application region whose Jobname is not listed in the table.
Jobname problems may occur when PREFERENCE volumes are copied from one system
to another. In this case, Jobname table entries may be keyed to jobnames
associated with one of the systems but not the other.
Click here for information on how to determine if "PREFERENCE
Help Requests are failing. Could it be due to the jobname of the application
region?". If
you find the associated Jobname table is empty, continue to the next step.
However, if the Jobnames table is populated, you need to ensure the table
contains the jobnames for all application regions to receive PREFERENCE Help.
If this is a test system or if there is a single jobname entry in the table,
you can quickly determine whether the correct jobname is being referenced by
removing the entry and re-trying the help request. If the problem no longer
occurs, the jobname entries you deleted were causing the help request to fail.
If the problem persists with an empty Jobnames table, put back the jobnames
that you removed and proceed to the next step.
-
Check the
Screen Rules Table. From the volume rules table, identify the application Transaction ID in the
Descriptors Table and access the Screen Rules Table (F7 Screens) for the
Transaction ID. You want to verify that a "match" occurs between character
strings on the application screen and one of the table entries. Reasons for a
"mismatch" include changed text on an application screen, casing, misspellings,
incorrect use of wild card characters etc,
-
Get a
PREFERENCE Trace. The PREFERENCE Trace facility displays detailed processing
information for specific help requests Access the
PREFERENCE trace facility as supervisor from the Supervisor
Rules Administration screen (type "rules" at the command line)
by pressing F9 Trace. Writers may require supervisor
authorization to access the trace facility in individual
volumes. Toggle trace ON using F9 and then F5 Clear to
empty the Trace table. Traces are keyed to a specific terminal
id or to a catch-all (*&) terminal id. For detailed
information about accessing PREFERENCE Trace facility and set-up
click here.
After exiting the trace facility, request help at the application screen and
then re-access the trace facility.
-
Check the
"Last Trace" field in the upper right part of the trace screen. The date and
time should be current. If this field is empty PREFERENCE trace is not
gathering information. Double check that trace is "ON", and that the specified
Terminal ID is valid and try again. If setup is correct and no date appears in
the PREFERENCE Trace Table, it may indicate that help requests are not being
navigated to this system.
-
The "Passed Descriptor" should show the Transaction ID of
the field in row 4. If you see
something unexpected Click here, it may be that you have misidentified the Transaction
ID of the application.
-
If a jobname
appears in the Trace table (row 7), compare it with any entries in the Jobname
Table (step 5. above). A jobname mismatch can occur if PREFERENCE volumes are
moved form one system to another (say, from development to production) where
different jobnames are utilized.
Back to Top
Generic Procedure
for Help Requests "Going Nowhere"
Outlined below are the
typical "first pass" steps taken by SumTotal technical support to resolve a
situation where help requests result in no change to the application screen or a
screen refresh.
-
Verify that
the PREFERENCE authorization code has not expired. An expired
authorization code means that PREFERENCE is not available.
Click here for information on "How to ensure
that your system authorization has not expired".
-
Verify that
you are pressing the correct Help Key. If no help key is defined or if you
are pressing the wrong help key, no help screen will appear. To verify
you may have to contact the application programmer and verify what help key
or keys are defined for the application environment.
Click here for information on "How to Ensure
you have a PF-Key defined for PREFERENCE Help".
-
Verify that
PREFERENCE is running.
If the PREFERENCE job has been stopped and not restarted (PREFERENCE is down),
help requests will not be processed. Attempt to sign-on to the PREFERENCE
system you are using for help requests through a "normal" VTAM sign-on.
-
For CICS
help requests, verify that CICS is connected to PREFERENCE. If CICS is
connected to PREFERENCE, clearing the CICS screen, typing "PRDP" and pressing ENTER should result in the PREFERENCE sign-on frame being
displayed.
-
Verify that
the Global Exit is enabled. This will require someone with authority
to issue the PREFERENCE "PRDA" transaction. The "PRDA"
transaction is designed to enable the PREFERENCE CICS Global Exit. If
our exit is already enabled when the "PRDA" transaction is entered, the
user will receive a response of "GC710 GOALSYS - PREFERENCE Global Exits
already "CICS ENABLED".". If our exit has not been enabled, then the
user should receive a response of "GC600 GOALSYS - PREFERENCE/CICS CBRCDZrr
EXIT ENABLED, GLOBAL AREA ADDRESS xxxxxxxx ". If a different response is
received and you need further assistance, please contact SumTotal technical
support.
Click here for
information on contacting SumTotal technical support.
Back to Top
PREFERENCE and Change Management
As previously discussed,
asking the question "what has changed?" can be valuable for resolving a rules
problem. Managing change however, ultimately involves preventive action that
can avoid problems before they occur. Awareness of change management issues is
an important first step in controlling the effects of change and minimizing the
extent that "change controls you". Here are some of the important issues that
you should be aware of:
Changes in operating
environment are
generally changes that are external to the PREFERENCE product, and may include
new versions of the IBM z/OS operating system, CICS or IMS. The SumTotal
Pathlore website maintains several "system compatibility" statements that
specify how changes to your technical environment may affect PREFERENCE
performance.
Click here to
link to this website.
Changes in application
environment can
include new application screens as well as modifications to existing application
screens. Modifications to application screen such as changes to the number of
input fields, verbiage, spelling and casing can all affect rules processing.
In an IMS environment application changes can include MOD definitions and
locations.
PREFERENCE product
upgrades generally occur every 2-3 years and include added functionality.
SumTotal maintains a release-support document on its Pathlore website and you
should consult this for release information and to make sure your version of
PREFERENCE is fully supported.
Click here to view the Pathlore release support document. Additionally
it is important that you follow correct procedures in implementing the upgrade
process.
Click here for instructions and technical information to aid in
executing a successful PREFERENCE product upgrade. Once you
have successfully tested this release on your test system, click
Click here for instructions on how to migrate the new release from your test system
to your production system.
PREFERENCE product
fixes address known product bugs and are published on the Pathlore mainframe
web-site for fully supported releases.
Click here to view the currently available fixes.
Migrations of
PREFERENCE volumes from one system to another system
(development, test and production, for example) need to be carried out
correctly. There are some specific areas where problems can arise after such a
migration:
-
Jobname entries defined in the Jobnames table of volumes in a test or development system
may not match jobname entries used in production.
-
Screen
rules that work
in a test or development system may not work in a production environment if
application screens are different.
-
IMS Mod
definitions that
work in a test or development system may not work in a production environment if
application screens are different.
-
Group
volumes that are
migrated from a test or development system to production need all member
volumes migrated at the same time or index terms in master index may not match
the index lists in member volumes.
-
Incorrect
PREFERENCE dataset names can copy the wrong reference material (for
example from a dataset no longer in use) into a live system.
-
If you are
using a single system and rename your volumes to create production
volumes, remember that the writer "force toc" command needs to be invoked to
update the volume name for internal index term storage.
Personnel changes can range from a key person going on vacation to someone permanently moving
on. In any case, it makes sense to train back-up personnel and keep them
informed about when experienced staff will be unavailable.
Back to Top
Contacting SumTotal Technical
Support
SumTotal provides full technical support for PREFERENCE customers running on a
supported release and who are on the SumTotal Customer Care Plan (CCP). To
facilitate handling of your technical support issue, be sure to include the
customer name and SumTotal/Pathlore customer number in the initial
communication.
Click here for
information on contacting SumTotal technical support.
Back to Top
LINKS TO ONLINE PREFERENCE
DOCUMENTATION
Here are links to the
SumTotal website for PREFERENCE that can aid in trouble-shooting PREFERENCE help
requests:
Back to Top
|
|
|
Order
Your Upgrade Today!