Dictionary/204 Cross-Reference facility
Overview
The Cross-Reference facility produces reports for users who develop and maintain Model 204 SOUL (User Language) procedures. The output reports show the line numbers where language elements such as labels, functions, and variable names occur in a specified set of procedures.
The Cross-Reference Report is produced in batch mode (by a batch job in z/OS and z/VSE, by a service machine in z/VM). Before submitting a cross-reference job, you can specify:
- Set of procedures in a procedure file or group
- Set of language elements to be cross-referenced
- Substitute values for SOUL global dummy strings
- Job-related parameters such as output destination and lines per page
All these selections are made through a full-screen interface, which is accessible from both the Dictionary/204 main menu and Model 204 command level. The Cross-Reference facility also includes Preview and Browse functions, which inform you about the procedures selected for processing.
Each authorized user of the Cross-Reference facility starts with a standard set of defaults for procedure and element selection. These defaults are stored in the user's profile record. As the facility is used, each user's profile is modified automatically to reflect the most recently chosen options.
Each user also has a default job procedure, which can be edited from within the Cross-Reference facility.
The availability of defaults for almost all options makes it possible to use the Cross-Reference facility without detailed knowledge of procedures or job control parameters. For example, if you are familiar with both SOUL and job control, you can select a set of procedures, assign appropriate values to all global dummy strings, change the output destination, and decide whether to designate batch processing as immediate or deferred. If you have no knowledge of programming, you can generate a report simply by opening a procedure file and submitting a job, using standard defaults set up by the dictionary administrator.
Using the Cross-Reference facility
Access privileges
The dictionary administrator authorizes access to the Cross-Reference facility by updating your account through Security Administration. See Defining, updating, and deleting ACCOUNT privileges for details.
if you are authorized to use the cross-reference facility, the dictionary administrator can create a default job procedure associated specifically with your Model 204 user ID. You also have a user profile, which stores default values for procedure selection and report options.
If the dictionary administrator removes your Cross-Reference facility privileges, then the user profile and job procedure are both deleted.
Opening the procedure file or group
The file or group containing the procedures that you want to cross-reference must be open in order to view procedure names or generate reports:
- You can issue the appropriate Model 204 OPEN or OPENC command before invoking the Cross-Reference facility.
- You can also open files or groups from the command line on the Cross-Reference Selection screen. In this case, use the syntax for the OPEN and OPENC statements in SOUL. See DDMIG IMPORT command for details.
If you plan to generate Cross-Reference Reports frequently for some set of procedure files, the system administrator can add them to the Cross-Reference facility subsystem definition. It is then unnecessary to open those files before submitting jobs.
For details on OPEN syntax and subsystem definition, refer to:
OPEN statement and OPENC statement
Invoking the facility
Choose one of the following ways to invoke the Cross-Reference facility:
- Select the facility from the Dictionary/204 main menu.
- Invoke it from the main screen of any other Dictionary/204 facility, by entering "INV XREF" on the command line.
- Type XREF (with no further arguments) at Model 204 command level, and press Enter.
- Enter a more complex form of the XREF command at Model 204 command level, as follows.
The first three methods of invoking the Cross-Reference facility take you to the Selection screen, described in the next section. The fourth method bypasses the full-screen interface, and submits a batch job directly.
XREF: Generating a SOUL (User Language) Cross-Reference report
Privileges
Any user
Function
Creates a cross-reference report for a specific set of SOUL procedures
Syntax
XREF [* [procname] | [FILE | [TEMP | PERM] GROUP] name procname]
Usage notes
At Model 204 command level, you can issue the following forms of the XREF command:
| Command | Description |
|---|---|
| XREF | Brings up the Cross-Reference Selection screen. |
| XREF * | Submits a cross-reference job using the default procedure selections and report options in your user profile record. |
| XREF * procnam > | Submits a cross-reference job for a single procedure in your default procedure file or group, using your default report options. For procname, type the name of the procedure to be cross-referenced. |
| XREF context procname | Submits a job for a single procedure in a file or group other than your default. For context type FILE, GROUP, TEMP GROUP, or PERM GROUP followed by the file or group name. For procname, type the name of the procedure. |
When several users are logged in to the same Model 204 ID, only one at a time is allowed to use the Cross-Reference facility. An error message is displayed if you try to invoke the facility when another user with the same ID is using it.
Open the procedure files in which the procedures reside before invoking the Cross-Reference facility. (If you use XREF without any parameters, you can open the procedure files through the screen interface that you enter.)
You can set substitution values for global dummy strings, as described in Dummy entries.
XREF support for Block Comments
When each user enters the XREF screen for the first time, the user must enter the COMSTART and COMEND characters that designate a Block Comment in procedures that a user is going to process.
A profile record is stored for each user that contains the last COMSTART and COMEND characters the user entered on the screen. On a subsequent entry into XREF, those COMSTART and COMEND characters are displayed on the screen. If you type over the displayed characters, the new characters are stored in your profile record. The following figure displays the Cross Reference Selection screen with the COMSTART and COMEND fields.
Cross Reference Selection screen
XRSL Cross Reference Selection VER 6 REL 1 Procedure file/group . . . ______________________ Report options All . . . . X Statement labels . . _ Lists/Positions. . . . . . _ Variables. . . . . . _ Subroutines. . . . . . . . _ Field names. . . . . _ Images/Menus/Screens. . . ._ Functions. . . . . . _ Dummy strings. . . . . . . _ Files/Groups/DAF . . _ Expand INCLUDEs (Y/N) . . . N Procedure selection criteria Proc Names or Patterns (N/P) . N COMSTART: /? COMEND: ?/ _____________________________________________________________ _____________________________________________________________ _____________________________________________________________ _____________________________________________________________ ===> 1=HELp 2=REFresh 3=QUIt 4=EDIt job 5=PREview 6=SUBmit 9=BROwse 10=GlObals 12=END
Cross-Reference Selection screen
To use the full-screen interface, you can either select the Cross-Reference facility from the Dictionary/204 main menu, or issue the command XREF (with no arguments) at Model 204 command level.
The first screen displayed is the Selection screen. Here you enter the information required to select procedures and report options. PF keys and the command line provide access to all other Cross-Reference facility functions.
This section explains the choices presented on the Selection screen and the general purpose of each PF key and command. The following sample screen shown has selections filled in:
Selecting a procedure file or group
To the right of the Procedure file/group prompt, fill in the name of the file or group that contains the procedures to be cross-referenced. Use any format recognized by the Model 204 OPEN command: simply the name, or the name preceded by FILE, GROUP, TEMP GROUP, or PERM GROUP.
If you select a multiple procedure file group, then the Cross-Reference facility searches all files in the order determined by CREATE GROUP.
If you have not opened the procedure file or group prior to invoking the Cross-Reference facility, you can do so by entering an OPEN or OPENC statement in SOUL format on the command line at the bottom of the screen.
Selecting Report Options
The Report Options portion of the screen selects SOUL elements to be included in the Cross-Reference Report. Make selections here by typing an X (or any other nonblank character) to the right of each item selected.
You can either select report options individually, or select All and leave the individual options blank. The language elements you select appear in sorted groups in the Cross-Reference Report. For example, if you select Variables and Functions, the report includes a list of variables in alphanumeric sort order, and a separate list of functions.
The items you select under Report Options represent syntactic elements that can be recognized by the Cross-Reference facility's internal parser. For example, if a statement in your procedure begins with the keyword IN, then the parser identifies the next string as the name of a Model 204 file or group.
Language elements
The Cross-Reference Report groups language elements as follows:
| Element | Includes... |
|---|---|
| Label | Both statement labels and statement numbers. |
| Variable | Variables preceded by a percent sign (%) but not those preceded by %% and :%, which are treated as field name variables and image/menu/screen items, respectively. |
| Field name | Both Model 204 field names and variables preceded by %%. |
| Function | All functions preceded by a dollar sign ($), whether they are standard Model 204 functions or created by the user. |
| File/Group/DAF | Model 204 files, groups, and DAF entities such as processes, conversation IDs, and destinations. For example, the names following the OPEN, IN, OPEN PROCESS, and RECEIVE commands are grouped in this category. |
| List/Position | All SOUL lists encountered in such context as the CLEAR LIST and PLACE RECORDS statements, and all SOUL positions encountered in such context as the POSITION and REMEMBER statements. |
| Subroutine | Simple and complex SOUL subroutines. Complex subroutines outside of BEGIN/MORE/END loops can be cross-referenced. This category also includes ON units. |
| Image/menu/screen | Both the names of these elements and their component parts. For example, variables preceded by :% are grouped in this category. |
| Dummy string | Include strings preceded by ??, ?&, or ?$. There are several options for referencing global dummy strings; these are explained in the next section and in Setting values for global dummy strings. |
For more information on SOUL syntax, refer to:
Overview of Model 204 commands
Global dummy strings
The Cross-Reference facility provides a special set of options and functions for the resolution of global dummy strings.
Global dummy strings are SOUL variables with the prefix ?&. When a procedure is included, a value is substituted for each dummy string. The replacement value can be either supplied by the user or read from a global variable table.
One common use of global dummy strings is to specify the next procedure to be included. For example, the following statement can be resolved as IN TEMPPROC INCLUDE BILLSYS.PROC1 or as IN BILPROCS INCLUDE BILLSYS.PROC2, depending on the contents of the global variable table:
IN ?&PROCFILE INCLUDE ?&NEXTPROC
This programming technique is explained in Using ?$ and ?& dummy strings.
In the Cross-Reference facility, you can use one of the following methods to provide values to be substituted for global dummy strings encountered in procedures to be cross-referenced:
- You can access the global variable table by using the $SETG function before invoking the Cross-Reference facility.
- You can specify substitute values on the Dummy String Resolution screen within the Cross-reference facility. This screen can be accessed from the Selection screen by pressing PF10.
These methods are explained in detail in Setting values for global dummy strings.
The more substitute values you enter for dummy strings, the closer your Cross-Reference Report becomes to the code that is executed at INCLUDE time. For example, if you substitute BILLSYS.PROC1 for ?&NEXTPROC, then all the SOUL elements in BILLSYS.PROC1 can be cross-referenced.
Dummy string options on the Selection screen have the following effects:
- Selecting the Dummy Strings option means that you want the dummy string names (such as ?&NEXTPROC) to be cross-referenced. The substituted values are not cross-referenced, but lines with resolved values appear in your output procedure listing. The line with the dummy string name is numbered, and the line with the resolved value is unnumbered and marked with asterisks.
- Leaving the Dummy Strings option blank means that you want to cross-reference substituted values (such as BILLSYS.PROC1). In your output procedure listing the line with the resolved value is numbered, and the line with the dummy string name is unnumbered and marked with asterisks.
- Whichever option you select, the Cross-Reference facility uses substituted values of global dummy strings for the purpose of expanding INCLUDEs. If any substituted value is a procedure in your open file or group, and you choose to Expand INCLUDEs, then language elements in the procedure are also cross-referenced.
- Remember that selecting All for Report Options has the effect of cross-referencing dummy string names, not values.
For examples of global dummy strings in the output listing, see Cross-Reference Report.
Expand INCLUDEs
On the "Expand INCLUDEs" line, you must type Y or N. If you select Y, then the Cross-Reference facility scans every INCLUDE command or statement in your procedure, searches for the included procedures or subroutines, and cross-references all included code that is found.
You can override this option in a Model 204 procedure by inserting one of the following lines before any INCLUDE statement:
*EXPAND (overrides N) *NOEXPAND (overrides Y)
Cross-references of included code are generated for all language elements selected, including dummy strings and nested INCLUDEs up to the five levels permitted by Model 204.
The following restrictions apply to cross-references generated for INCLUDEs:
- Conditional INCLUDEs are listed as procedures in the top-down and bottom-up sections of your report, but are never expanded.
- If an INCLUDE statement is not preceded by an IN clause, then the assumed context always comes from your user profile. Thus, DEFAULT or OPEN statements in your procedures are ignored by the parser in determining the context of subsequent INCLUDEs.
Selecting procedures
Choose one of the following methods to select procedures to be cross-referenced:
- Enter procedure names on the bottom four lines of the screen
- Enter patterns for procedure names on the bottom four lines
To enter names, type N to the right of the "Proc Names or Patterns" line. You can enter several procedure names on the same line by separating the names with semicolons or any number of spaces. For example, the following line is recognized as a valid request to process three procedures:
BILLSYS.PROC1;BILLSYS.PROC2 BILLSYS.PROC3
To specify a pattern, type P. This informs the Cross-Reference facility that you want to use pattern-matching rules.
If you select pattern matching, do not list procedure names; instead, type one or more patterns, as shown in the following sample screen.
The selections shown on the following screen generate a report for all procedures in the BILPROCS file that begin with the string BILLSYS.
Screen commands, PF keys, and messages
To issue a command, press the assigned PF key, or type the command on the command line and press Enter. In the Cross-Reference facility, any command assigned to a PF key can be abbreviated by typing just the first three letters.
| Key | Command | Meaning |
|---|---|---|
| PF1 | HELp | Selection screen HELP text explains commands, PF keys, and your user profile record. |
| PF2 | REFresh | Erases your selections and displays the default options. |
| PF3 | QUIt | Exits from the Selection screen without saving any changes. |
| PF4 | EDItjob | Invokes the Model 204 full-screen editor to edit your job procedure. See Editing the cross-reference job procedure. |
| PF5 | PREview | Displays the number of procedures found according to your selection criteria. Displays errors if the criteria were specified incorrectly. |
| PF6 | SUBmit | Submits your cross-reference job for execution. |
| PF9 | BROwse | Displays a detailed list of procedures selected. Also displays pattern matching errors and named procedures that are not found. See Reviewing procedure selections. |
| PF10 | GLObals | Displays a screen on which you can specify substitute values for global dummy strings. See Setting values for global dummy strings. |
| PF12 | END | Saves changes entered on the screen and exits. |
You can also issue OPEN and INVOKE commands from the Selection screen command line:
| Command | Meaning |
|---|---|
| OPEN or OPENC | At the command prompt (===>) type any form of the SOUL OPEN or OPENC statement and press Enter.
If the file or group to be opened requires a password, enter it as you issue the command. For example: OPEN BILPROCS PASSWORD ZELDA In this command format, password entry is visible; if you do not want passwords to be visible as you enter them, you must exit to command level to open files. |
| INVoke | You can transfer directly to another Dictionary/204 facility by typing at the command prompt:
INVoke <facility name> Then press Enter. When you exit the invoked facility, you return to the Cross-Reference facility. |
After you issue a command from the Selection screen, a message is displayed on the line above the command line. Informational messages report the results of issuing a command. For example:
XRF041 File/Group successfully opened.
XRF038 cross-reference job has been submitted.
Error messages report user errors, access conflicts, and various kinds of unsuccessful operations. For example:
XRF014 Please specify "N" or Names or "P" for Patterns.
XRF044 The specified procedure is currently in use.
XRF019 Pattern matches no procedure names.
Setting values for global dummy strings
This section explains how to assign values for global dummy strings. Choose one of the following methods:
- Run a procedure using the $SETG function
- Specify values on the Dummy String Resolution screen
You can use these methods simultaneously. Values set by $SETG take precedence over values specified on the Dummy String Resolution screen. The Cross-Reference facility searches for both types of substitution values, and uses whatever values are available.
Selecting Report Options explains the reasons to provide substitution values for global dummy strings.
Using the $SETG function
The first method requires executing a SOUL procedure, or subsystem, immediately prior to entering the Cross-Reference facility. The SOUL $SETG function can be used to place values for critical global variables in the global variable table. This technique is often used in the initial LOGIN procedure of application subsystems.
Running a SOUL procedure like the following sets each global variable referenced to the value specified in the $SETG functions:
UTABLE LGTBL=1200 BEGIN IF $SETG('NEXTPROC','BILLSYS.PROC1') OR - $SETG('PROCFILE','BILPROCS') THEN PRINT 'GTBL IS FULL' END IF END
It is important to set the LGTBL parameter using the UTABLE command, because the Cross-Reference facility itself needs 1000 bytes to operate. If LGTBL (the size of the table where globals are stored) is set to less than 1000, then the Cross-Reference facility resets it to 1000, destroying the contents of all preset global variables.
Therefore, compute LGTBL as follows:
LGTBL = 1000 + length+1 of all global variable names + length+1 of all global variable values
Do not use $SETG to set any global variables that are named XFER or that begin with the prefix CCA. These names are reserved for use by the Cross-Reference facility.
Note: Invoke the Cross-Reference facility by issuing the XREF command immediately after the procedure executes. Otherwise, the global variable values might be destroyed and the LGTBL parameter reset.
Using the Dummy String Resolution screen
To set global substitution values within the Cross-Reference facility, press PF10 on the Selection screen to bring up the Dummy String Resolution screen. The following screen example is shown with two entries.
Without the values entered on the sample screen (or set using $SETG) the facility would not, for example, be able to recognize that the following SOUL statement:
IN ?&PROCFILE INCLUDE ?&NEXTPROC
can be resolved at INCLUDE time to the following statement:
IN BILPROCS INCLUDE BILLSYS.PROC1.
The basic editing functions are performed directly on the screen:
| To... | Do this... |
|---|---|
| Change lines in the table | Move the cursor to the strings or values you want to change and type over them. |
| Delete lines | Type spaces over them. |
| Add global strings and values | Type them in on the blank lines provided, scrolling forward if you have filled a screen. |
You can add as many values as you want; the size of this table is limited only by the size of M204DCTL, the Model 204 file that contains Cross-Reference facility user defaults.
On this screen, the maximum length allowed for dummy strings is 20 characters. For substituted values, the maximum length is 50 characters.
Dummy strings are listed in the order in which you entered them. If your table takes up more than one screen, then the upper-right corner of the screen displays the line numbers you are viewing.
While editing the global substitution table, make sure that it conforms to the following rules:
- For every dummy string, there must be a value.
- For every value, there must be a dummy string.
- No dummy string name can have imbedded spaces, or special characters other than periods.
- Duplicate global dummy string names are not allowed.
If any of these rules is violated and you attempt to save changes, an error message is displayed.
Dummy String Resolution screen: PF keys and commands
PF keys and commands perform as follows:
| Key | Command | Meaning |
|---|---|---|
| PF1 | HELp | Global HELP text describes commands, PF keys, and rules for editing. |
| PF2 | REFresh | Erases the entire list of global dummy strings and values.
Note: These are not erased from your user profile until you press PF12. |
| PF3 | QUIt | Exits to the Selection screen without saving any changes. |
| PF7 | BACkward | Scrolls backward so that the current top line on the screen becomes the bottom line. |
| PF8 | FORward | Scrolls forward so that the current bottom line on the screen becomes the top line. |
| PF12 | END | Saves all edits in your user profile and exits. |
As on the Selection screen, any command assigned to a PF key can be entered on the command line.
If you press Enter after making changes, then your changes are checked for errors and the appropriate messages are displayed. Otherwise, the Enter key has no effect on this screen.
Reviewing procedure selections
The PREVIEW and BROWSE commands allow you to verify your procedure selections before you submit a cross-reference job.
PREVIEW command
The PREVIEW command displays brief messages about your procedure selection criteria above the Selection screen command line.
If you press PF5 or enter PREview on the command line, the Cross-Reference facility searches for procedures that fit your selection criteria.
If specifications contain any errors, or if named procedures are not found, then an error message is displayed above the command line. For example:
XRF015 Please specify at least one procedure name or pattern
If procedures are found that fit your criteria, then an informational message is displayed telling you how many. For example:
XRF020 Number of procedures found: 6.
BROWSE command
The BROWSE command (PF9 on the Selection screen) displays a more complete report on found and unfound procedures.
Suppose, for example, that you have five BILLSYS procedures in your procedure file. On a Friday afternoon you enter the following list of procedures to be cross-referenced:
BILLSYS.PROC1;BILLSYS.PROC2;BILLSYS.PORC3 BILLSYS.PROC4BILLSYS.PROC5 BILLSYS.PROC6
Notice that PROC3 is misspelled and that PROCS 4 and 5 run together. PROC6 is specified correctly, but it does not exist.
In this case, if you press PF9, the following screen is displayed:
The first section of the BROWSE display (named procedures not found) helps identify various errors in specifying procedure selection criteria. If a procedure is listed here with the correct spelling (as is PROC6 in the example) then it is not in your procedure file or group.
The second section of the BROWSE screen displays detailed information about the procedures successfully selected:
- Date and Time columns display the time of the latest update of each found procedure.
- If the context specified is a group with multiple procedure files, then the BROWSE function displays a Filename column instead of the Time column.
- Length column displays the length in bytes of each found procedure. This figure can be useful if you need to calculate temporary disk space required for batch processing (see Editing the cross-reference job procedure).
BROWSE is a read-only function that has no effect on your options or defaults. Therefore, the available PF keys all control movement within the display. You can locate any string by typing it on the command line and pressing PF5.
Editing the cross-reference job procedure
This section is for users who have some familiarity with job procedures and batch processing. If you are not familiar with the job procedure language in use at your installation, use the default procedure set up by your dictionary administrator.
The generic cross-reference job procedure is stored as a Model 204 procedure named XREF.SYSTEM.jtype in the file M204DCTL, where jtype stands for JCL, EXEC, or JECL depending on whether your operating system is z/OS, z/VM, or z/VSE.
User job control procedures are named XREF. userid.JOB. They are also stored in M204DCTL.
To create a new user job procedure, issue the following Model 204 commands (with the appropriate values for jtype and userid ):
OPEN M204DCTL COPY PROCEDURE XREF.SYSTEM.jtype TO XREF.userid.JOB
Pressing PF4 (EDItjob) at the Selection screen allows you to edit your user job procedure, using the Model 204 full-screen editor. You can edit any line, but, in general, restrict your changes to installation-specific parameters such as output destination and job class.
When you edit your job procedure, take note of the following guidelines:
- The placeholder line is marked by the string //*M204XREF. Whenever you edit the job procedure, make sure that you do not delete this line. It marks the place where the selected procedures are inserted in the batch jobstream.
- Space allocation parameters specify a temporary data set or z/VM file with DDNAME = CCAREF. If you are submitting large jobs, you might want to increase the space parameters. You can estimate your temporary space requirements as follows: select a relatively large number of procedures on the Selection screen, press PF9 to BROWSE, and multiply the total bytes of the procedures displayed by 30.
- If you increase the temporary space parameters, find the sort step and increase the space for sort work data sets proportionately.
- The LPP parameter in your job procedure sets the number of lines per page appropriate to your output device. In z/OS, this value is represented as instream data following the LPP DDname. In z/VM, a Rexx variable called lpp is initialized near the top of your EXEC.
It is useful to remember that instead of editing your procedure, you can always copy the generic job procedure (or another user's procedure) by issuing the GET command in the full-screen editor.
Submitting a job
If you are using the full-screen interface, submit a cross-reference job by displaying the Selection screen and pressing PF6. If the submission is successful, an informational message is displayed above the command line. If the submission is not successful, an error message is displayed.
Successful submission of a job means only that the selection criteria you specified are valid. If the procedures you selected contain syntax errors or otherwise unparseable statements, error messages are included in the output report.
After you submit the job, no further intervention is required; batch processing proceeds whether or not you exit from the Cross-Reference facility or Model 204.
Remember, however, that how you exit from the Cross-Reference facility determines whether the options you have just chosen are saved in your user profile and used for future sessions. The END command (PF12) saves changes; the QUIt command (PF3) exits without saving changes.
You can also submit a job without going through the full-screen interface by entering the XREF command with arguments at Model 204 command level. For details, see Invoking the facility.
Retrieving output
When Cross-Reference facility batch processing is completed, the output can be sent to a disk or directly to a printer. The output destination depends on parameters set in your job procedure.
Details and options such as job class, priority, message class, and output device vary widely among Model 204 installations. If you are not familiar with job control and batch processing at your installation, ask your dictionary or system administrator how to retrieve Cross-Reference Reports.
Cross-Reference Report
The Cross-Reference Report consists of several sections, arranged in the following format:
- Top-down list of procedures selected, with sublists of procedures they include.
- Bottom-up list of all procedures included, and the procedures that use them.
- Listing of each procedure, with sequential line numbers, parser errors flagged, and nesting levels marked by angle brackets.
- For each procedure, a set of Cross-Reference Reports for each language element selected.
This section explains the details of the output report, and provides further information on how to use the Cross-Reference facility most effectively.
Cross-Reference Report format
Cross-reference output is in standard 132-column format. If you route your report to a printer, make sure that it supports a line width of 132 characters.
On each page of the report is a header, which identifies the section and also displays general information such as the length and last update of the procedure selected.
Page breaks occur whenever a new section begins, and are otherwise controlled by the LPP (lines per page) parameter in your job procedure. (See Editing the cross-reference job procedure.)
If you are cross-referencing a long procedure, you can also use the following methods to control pages and spacing:
- Force a page break in the listing by inserting a comment line *EJECT in your procedure. The line *EJECT does not appear in the procedure listing.
- Force a space by inserting the comment line *SPACE, or by inserting *SPACE n, where n is the number of blank lines you want in the procedure listing.
- Avoid using comments beginning with *CTL and *XRF in procedures to be cross-referenced. These reserved prefixes might adversely affect the parser.
- All parsed lines in the procedures are assigned sequential numbers, which appear in the left-hand column of the procedure listing. Comments and continuation lines are not numbered.
- Global dummy strings and their resolved values are listed together. If you chose to cross-reference the names, the line with the name is numbered and the line with the value has a string of five asterisks in the "LEVEL" column. If you chose to cross-reference the values, the line with the names has the asterisks.
- Each procedure is numbered sequentially from beginning to end, and all its language elements are cross-referenced together. For this reason, a procedure containing multiple requests (BEGIN... END sections) might generate a less informative report than would an equivalent set of separate subroutines.
Note: Although many features of the Cross-Reference Report are useful for debugging, remember that the internal parser is not a compiler. Lines that cannot be parsed are flagged with a general error message, but syntax errors are not described in detail. For best results, make sure that your code conforms to currently supported syntax as described in the Statement syntax and Overview of Model 204 commands topics.
Expanding INCLUDEs whenever possible also improves the overall coherence of the report.
In order to correctly cross reference image definitions and declare statements, the full image definition must be available in the procedure. If the full image definition is not available, in some cases incorrect results might occur such as including %variable definitions as part of the image definition or the following message might be issued:
XRF100: UNABLE TO PARSE EXPRESSION - CHECK SYNTAX.
Examples
The following examples (presented in condensed form) illustrate some details of the cross-reference Report format.
Top down list
The top down and bottom up lists are useful when you select several procedures.
In this example the procedure PRE-ADD.DRV has been selected; it includes five other procedures, and the relevant INCLUDE statements are found on the lines indicated. The type UL STMT denotes an INCLUDE statement within a request. COMMAND denotes a Model 204 INCLUDE command.
PROCEDURE USES PROCEDURE LINE TYPE --------------------------------------------------------------- PRE-ADD.DRIV HELP.SCREEN 00031 UL STMT HELPSUB 00029 UL STMT ON.CONFLICT.ERROR.UNITS 00101 UL STMT SCREEN.DEFAULTS 00004 UL STMT UPD.DRIV.SCREEN 00002 UL STMT UTABLE.CHECK 00500 COMMAND
Bottom up list
This is a similar report, from the called procedure's point of view. In this case, HELPSUB is called by two different procedures in the set selected.
PROCEDURE USED BY PROCEDURE LINE TYPE --------------------------------------------------------------- HELPSUB PRE-ADD.DRIV 00029 UL STMT PRE-UPD.DRIV 00014 UL STMT
Context, nesting level, and globals
This excerpt shows the first few lines of the PRE-ADD.DRIV procedure listing. A screen is defined within an included procedure, using another procedure called SCREEN.DEFAULTS. Each angle bracket (>) in the LEVEL column shows a nesting level. In the header, CONTEXT indicates the procedure file or group in which PRE-ADD.DRIV resides.
The user selected the Dummy String report option, so dummy string names (not substituted values) are to be cross-referenced. In the listing, the substituted value for "??TAG" appears as an unnumbered line.
PROCEDURE: PRE-ADD.DRIV CONTEXT: AUTOPROC UPDATED: 1/30/90 16:29 LENGTH: 5465 LINE NO LEVEL SOURCE LISTING ----- ----- ------------------------------------------------- 00001 B 00002 IN AUTOPROC INCLUDE UPD.DRV.SCREEN 00003 > SCREEN UPD.DRIV 00004 > IN AUTOPROC INCLUDE SCREEN.DEFAULTS X 00005 >> DEFAULT PROMPT BRIGHT 00006 >> DEFAULT INPUT PAD WITH '_' TAG BRIGHT WITH '??TAG' ***** DEFAULT INPUT PAD WITH '_' TAG BRIGHT WITH 'X' 00007 >> MAX PFKEY 12 00008 > PROMPT USC1
Variables
Variables (like other language elements) are grouped together and listed in alphanumeric sort order.
The DEFN column indicates the line where a variable is explicitly declared. This column is blank for undeclarable items such as files, fields, and functions. Other possible DEFN values are:
- DEFAULT
- *UNDEF for undefined image, menu, or screen items
- SYSTEM for reserved names such as PFKEY.
The variable %FULLNAME has a line number in the DEFN column, because line 174 of PRE-ADD.DRV is:
%FULLNAME IS STRING LEN 75.
An asterisk to the right of a line number in the REFERENCES column indicates a line where the value of a variable is altered. For example, line 256 is:
%FULLNAME = %UPD.DRIV:LNAME WITH %UPD.DRIV:FNAME.
The variable %LINE is in the complex subroutine HELPSUB, the name of which is appended in parentheses. Complex subroutine names are also appended to image and screen items, lists, and labels.
PROCEDURE: PRE-ADD.DRIV CONTEXT: AUTOPROC UPDATED: 1/30/87 16:29 LENGTH: 5465 VARIABLE DEFN * R E F E R E N C E S * --------------------------- ------ --------------------------------- %ENQCTR DEFAULT 000142 000151* 000155 000235 %FULLNAME 000174 000256* 000261 %I DEFAULT 000271* 000272 %LINE (HELPSUB) DEFAULT 000084*