HP 3000 Manuals HP 3000 Manuals
OCA Report Formats A report is automatically generated for each file that OCA scans. There are two formats of the report: * Brief format * Detailed format The brief report format provides only information directly related to the ability of the program or SL file to migrate successfully. This information includes a list of potential incompatibilities detected when OCA scanned the selected program or SL files. Appendix D, "Incompatibilities", provides detailed descriptions and corrective actions to take for each of the incompatibilities detected by OCA.
NOTE It is highly recommended that you run the brief report first. Run the detailed report only on programs which have potential incompatibilities as identified in the brief report, or if the additional information is needed.
The detailed report format provides more information about the program than in the brief report format. It also provides the code locations of potential incompatibilities. This should be done only on programs which have incompatibilities as reported by the OCA brief report (and not disqualified by RTM). A detailed report can be used to locate privileged segments or provide a better understanding of the program's structure. The content of this report differs slightly depending on whether the file is a program file or an SL file. If you have the source file, following are two alternatives to using the detailed report to obtain the code location of incompatibilities. After you have used the OCA brief report format to identify the names of incompatible external procedures: * Use an editor to find the exact location in your source file of the call to the incompatible procedure. * Use the compiler listing and a cross reference to find the exact location of the call to the incompatible procedure. Output Device Specification If you use the ;OFFLINE option, you can direct OCA report or HELP text output to the OCA list file OCALIST. By default this file is assigned to the system line printer (DEV=LP). If you want to redirect output to a different device, you can create an MPE file equation using the :FILE command (either at the SCAN prompt or prior to running OCA) to redefine the characteristics for OCALIST. This file equation is invoked for file specification only if you specify ;OFFLINE. In the following example, the :FILE command, is invoked at the SCAN prompt to create a file equation for OCALIST then a file name is specified with the ;OFFLINE option: SCAN>:FILE OCALIST;DEV=EPOC SCAN>@TOOLS.SWAT;OFFLINE SCAN>?;OFFLINE At any prompt, you can use the ;OFFLINE option immediately after a question mark "?" to redirect the HELP text output associated with that prompt. In the example above, HELP text about the SCAN prompt is redirected to device EPOC. Contents of Brief and Detailed Report Formats The following tables summarize the types of information returned in the brief and detailed reports created by OCA. The tables mirror the sequence of sections of the OCA report. Sections printed only for program files are noted in the table description: * General Information (returned for program files only) * Segment Information * Resolved External Procedures * Unresolved External Procedures (returned for program files only) * Potential Incompatibilities * Intrinsic Mechanism Information General Information. Table B-1 summarizes the information returned in the "General Information" section of an OCA report. This information is returned only for program files; segmented library (SL) files do not have equivalent characteristics. The first two categories of information indicate potential migration issues. You should pay particular attention to whether or not the program file was prepped with Privileged Mode (PM) capability. In this case, check to see if your program file contains Privileged Mode segments. In general, use of Privileged Mode code in an application is much more likely to cause migration-related problems. Table B-1. General Information (program files only) ----------------------------------------------------------------------------------------------- | | | | | Information | Brief | Detailed | | | | | ----------------------------------------------------------------------------------------------- | | | | | Program capabilities(for example, IA,BA,DS,PM) | X | X | | | | | | Are there privileged segments? | X | X | | | | | | Initial stack info: size of program global area | | X | | (DB-QI) | | | | | | | | Initial stack info: size of program global (DL-DB) | | X | | | | | | Initial stack info: size of initial DL area | | X | | | | | | Initial stack info: program of MAXDATA size (DL-Z) | | X | | | | | | Was a program prepped with; FPMAP option | | X | | | | | ----------------------------------------------------------------------------------------------- Segment Information. Table B-2 summarizes the information returned in the "Segment Information" section of an OCA report. The "Segment Information" section returns information about all program/SL segments, as well as information about possible patch areas if the program/SL file is patched. If the "General Information" section of an OCA report indicates that the program file contains Privileged Mode segments, the "Segment Information" section is useful for determining which program/SL segments are privileged. Table B-2. Segment Information ----------------------------------------------------------------------------------------------- | | | | | Information | Brief | Detailed | | | | | ----------------------------------------------------------------------------------------------- | | | | | Table containing the segment name (SL files only), | | X | | segment number, segment length, and mode (User or | | | | Priv) | | | | | | | | Summary information: total code size | | X | | | | | | Summary information: average code segment size | | X | | | | | | Patch area information: program name(program fine | | X | | patch areas only) | | | | | | | | Patch area information: segment name | | X | | | | | | Patch area information: prep date/time | | X | | | | | | Patch area information: patch data/time | | X | | | | | | Patch area information: whether or not the patch area | | X | | has been altered | | | | | | | | Patch area information: an octal dump of the patch | | X | | area (only if the patch area has been altered) | | | | | | | ----------------------------------------------------------------------------------------------- Resolved External Procedures. Table B-3 summarizes the information returned in the "Resolved External Procedures" section of an OCA report. The "Resolved External Procedures" section of the report provides a complete list of all external procedures called by a program directly or indirectly. This section also provides a cross-reference of all the calls. External procedure calls originating from a segment in the system library SL.PUB.SYS will not be in the list. This section may be very long for large programs and for programs that use SL files. Hewlett-Packard recommends that you request this information only if you need to get a "feel" for what a program is doing, and how it does it (for example, if you are migrating a program you did not write). Table B-3. Resolved External Procedures ----------------------------------------------------------------------------------------------- | | | | | Information | Brief | Detailed | | | | | ----------------------------------------------------------------------------------------------- | | | | | The name of the external procedure | | X | | | | | | Library in which the external procedure resolved | | X | | (Group, Pub, System) | | | | | | | | Segment number of the segment(s) calling the procedure | | X | | | | | | SST number(s) for the PCAL to the procedure | | X | | | | | | PB relative offsets for the calls to the procedure | | X | | | | | ----------------------------------------------------------------------------------------------- Unresolved External Procedures. Table B-4 summarizes the information returned in the "Unresolved External Procedures" section of an OCA report. This section is printed only if the program file contains one or more unresolved external procedure references. This usually occurs when you do not specify the correct library at the SCAN prompt using the LIB= option. For best results, you should scan the program file using the same LIB= option as you would when you run the program. Table B-4. Unresolved External Procedures (program files only) ----------------------------------------------------------------------------------------------- | | | | | Information | Brief | Detailed | | | | | ----------------------------------------------------------------------------------------------- | | | | | A list of the external procedures which were | X | X | | unresolved | | | | | | | | The reason why the procedure was unresolved | X | X | | | | | ----------------------------------------------------------------------------------------------- Potential Incompatibilities. Table B-5 summarizes the information returned in the "Potential Incompatibilities" section of an OCA report. This section lists the potential migration issues you should expect to encounter.
NOTE You should read the messages encountered in this section, and refer to Appendix D, "Incompatibilities", for a more detailed explanation of the cause of the incompatibility, as well as possible corrective actions to take to remedy the problem.
It is possible that the OCA report may list calls to system intrinsics that you will be unable to locate in your code. This should not alarm you. Many MPE V/E compilers generate calls to system intrinsics on your behalf. For example, the COBOL II/V compiler generates a call to the system intrinsic XCONTRAP if you compile with the $CONTROL DEBUG option enabled. When you recompile your source code using an MPE/iX NM compiler, all compiler-generated external references will be properly handled by the compiler. It is also possible that the OCA report may list incompatibilities against SL procedures not actually referenced by the program. If your program refers to an entry in an SL segment (whether directly or indirectly), OCA scans all procedures found in the SL segment, whether or not they are actually referenced. This occurs because the whole SL segment (not just the referenced procedures) is bound to the program at run time. The recommended method of determining whether or not a reported procedure is actually called by a program is to enable RTM and run the program again. (For details on this method, refer to Appendix C, "Using the Run Time Monitor".) Table B-5. Potential Incompatibilities ----------------------------------------------------------------------------------------------- | | | | | Information | Brief | Detailed | | | | | ----------------------------------------------------------------------------------------------- | | | | | A list of all the incompatibilities detected | X | X | | | | | | The name of the incompatible procedure that is | X | X | | referenced. | | | | | | | | A brief message indicating the nature of the | X | X | | incompatibility. | | | | | | | | An indication of the mode in which a user would expect | X | X | | to encounter the problem (that is,CM only, CM/NM,NM | | | | only). | | | | | | | | A message number which can be cross-referenced with a | X | X | | number from RTM and looked up in Appendix D. | | | | | | | ----------------------------------------------------------------------------------------------- You can also use the source code of both the program and SL segments to determine which procedures are actually referred to by the program by successfully tracing reported procedures back to the main program. If you are an advanced user of MPE V/E, you can use the OCA detailed report with LIB=G/P along with PMAPs (created with the MPE V/E SEGMENTER) of all SL segments in question. Cross reference all reported procedures and determine whether the procedures are actually referred to. Summary Information. Table B-6 summarizes the information returned in the "Summary Information" section of an OCA report. This section reports total numbers of events listed in the "Potential Incompatibilities" section of the report. Table B-6. Summary Information ----------------------------------------------------------------------------------------------- | | | | | Information | Brief | Detailed | | | | | ----------------------------------------------------------------------------------------------- | | | | | Total number of CM only incompatibilities detected | X | X | | | | | | Total number of CM/NM incompatibilities detected | X | X | | | | | | Total number of NM only incompatibilities detected | X | X | | | | | | Total number of user-defined incompatibilities | X | X | | detected | | | | | | | | Total number of uncallable procedures detected | X | X | | | | | ----------------------------------------------------------------------------------------------- Intrinsic Mechanism Information. Table B-7 summarizes the information returned in the "Intrinsic Mechanism Information" section of an OCA report. This section briefly describes the intrinsic mechanism issue related to migration, and lists all of the names of the system intrinsics your program references. Using this list, you can consult your source code to determine if you actually used the intrinsic mechanism. The intrinsic mechanism issue related to migration is discussed below. Table B-7. Intrinsic Mechanism Information ----------------------------------------------------------------------------------------------- | | | | | Information | Brief | Detailed | | | | | ----------------------------------------------------------------------------------------------- | | | | | A message briefly explaining the intrinsic mechanism | X | X | | issue | | | | | | | | A list of all the intrinsics that the application | X | X | | references | | | | | | | ----------------------------------------------------------------------------------------------- Although you may not recognize it by the name intrinsic mechanism, the intrinsic mechanism has been an MPE V/E feature for a long time. All of the programming languages supported on MPE V/E allow users to call system-supplied routines, called intrinsics, without explicitly declaring the intrinsic parameters. The compilers determine if you are calling the procedure correctly by examining the file SPLINTR.PUB.SYS, which contains the declarations for all the system intrinsics. The MPE V/E intrinsic mechanism is provided as a convenience for users. It is a shorthand notation for calling external procedures, but it does not cause the compiler to generate code any differently than if the procedure is declared as an external procedure and is called as in the example above. MPE/iX also supports a set of NM compilers which handle the intrinsic mechanism in a slightly different manner. On MPE/iX, the intrinsic mechanism plays a more important part in the compilation process. The intrinsic file on MPE/iX, SYSINTR.PUB.SYS contains more information about the procedure which is being called. For example, it contains information about the mode in which the procedure executes (CM or NM) and about how it can be accessed via the Switch subsystem. Furthermore, it contains crucial information about the parameter alignment necessary for calling the procedure. If you plan to migrate your application to NM on MPE/iX, you must use the intrinsic mechanism to get correct results. By mandating the use of the intrinsic mechanism and enhancing it to contain several new features, MPE/iX will be able to provide a programmatic interface which is more flexible and extensible than the one currently provided by MPE V/E. Each of the MPE V/E programming language reference manuals contain a section on how to call system intrinsics. These manuals can be consulted to determine the appropriate syntax for the language you are using. If you are already using the intrinsic mechanism (not explicitly declaring the procedures or allowing the compiler to do it implicitly), you will not encounter any problems in this area when migrating to NM on MPE/iX. All of the languages supported on MPE/iX in NM have their own migration guides. These guides will provide you with additional information on the subject of the intrinsic mechanism and how to deal with any potential issues which may arise when recompiling to NM. Some of the MPE/iX compilers support special migration related compiler options which can be of great assistance in determining if you have a problem in this area. COBOL II/XL, for example, supports a $CONTROL CALLINTRINSIC option which will generate a warning if your program contains calls to system intrinsics without using the intrinsic mechanism. It is possible that the OCA report may list calls to system intrinsics that you will be unable to locate in your code. This should not alarm you. Many of the MPE V/E compilers will generate calls to MPE V/E system intrinsics on your behalf. For example, most of the compilers will generate a call to the system intrinsic TERMINATE which handles terminating your process when your program is done executing. Any procedure names which you find in the list generated by OCA but cannot find references to in your source code fall into this category. When you recompile your source code on MPE/iX using NM compilers, all compiler-generated external references are handled through the intrinsic mechanism. Sample Brief Report Figure B-3 provides a sample of a brief OCA report. _______________________________________________________________________________________ | | | OCA HP30365A.00.05 (Cat A.00.05) - THU, OCT 23, 1986, 11:01 AM Page | | No. 1 Report for STICP.SOOL.MPEV ;LIB=G ;BRIEF | | | | G E N E R A L I N F O R M A T I O N | | | | Program was prepped with ;CAPS=BA,IA. | | Program contains only user mode segments. | | | | P O T E N T I A L I N C O M P A T I B I L I T I E S | | | | Incompatibilities detected in the program file "STICP.SOOL.MPEV". | | | | FCONTROL: *** System Defined Incompatibility *** | | - Some FCONTROL controlcodes are no longer valid | | on MPE/iX (CM/NM 500). | | These control codes include: 03, 48. | | | | Incompatibilities detected in the group SL (SL.SOOL.MPEV). | | | | CREATEPROCESS: *** System Defined Incompatibility *** | | - CREATEPROCESS may encounter byte pointer problems | | in NM on MPE/iX (NM 107). | | | | FCONTROL: *** System Defined Incompatibility *** | | - Some FCONTROL controlcodes are no longer valid | | on MPE/iX (CM/NM 500). | | These controlcodes include: 03, 48. | | | | S U M M A R Y I N F O R M A T I O N | | | | NM Only Incompatibilities:1 | | CM/NM Incompatibilities:2 | | Uncallable Procedures Detected:0 | | | | I N T R I N S I C M E C H A N I S M I N F O R M A T I O N | | | | | | Applications being recompiled to native mode must | | use the intrinsic mechanism for system intrinsics. | | | | Number of procedures requiring the intrinsic mechanism: 3 | | | | Procedures from STICP.SOOL.MPEV requiring the intrinsic mechanism:FCONTROL| | | | Procedures from SL.SOOLMPEV requiring the intrinsic mechanism: | | CREATPROCESS FCONTROL | | | _______________________________________________________________________________________ Figure B-3. Sample Brief Report Sample Detailed Report Figure B-4 provides a multipage sample of a detailed OCA report. It provides an expanded listing of general information, segment information, and resolved external procedures. __________________________________________________________________________________ | | | OCA HP30365A.00.05 (Cat A.00.05) - THU, OCT 23, 1986, 11:01 AM Page | | No. 1 Report for STICP.SOOL.MPEV ;LIB=G ;DETAILED | | | | G E N E R A L I N F O R M A T I O N | | | | Program was prepped with ;CAPS=BA,IA. | | Program contains only user mode segments. | | | | Program was prepped with ;CAPS=BA,IA. | | Program contains only user mode segments. | | | | Initial Stack Information: | | Size of initial DL area (DL-DB): 0 (%000000) | | Size of program global area (DB-QI): 284 (%000434) | | Size of initial stack (QI-Z): 4256 (%010240) | | ;MAXDATA= was not specified on :PREP command. | | | | S E G M E N T I N F O R M A T I O N | | | | Segment information for the program file "STICP.SOOL.MPEV". | | Total number of segments: 1 | | Starting segment number: 0 | | | | Segment Segment | | Number Length (%octal) Mode | | ================================================= | | %00000 76 (%00114) USER | | | | Total code segment size: 76 Average code segment size: 76 | | | | Information for referenced segments in the group SL (SL.SOOL.MPEV). | | Number of segments referenced: 1 | | | | Segment Segment Segment | | Name Number Length (%octal) Mode | | ============================================================= | | STICK %00000 72 (%00110) USER | | | | Total code segment size: 72 Average code segment size: 72 | | | | Information for referenced segments in the account SL (SL.PUB.MPEV).| | No externals resolved to this SL. | | NOTE : This application does not require this SL to migrate. | | | | Entry Point PB Relative Address Stt Number | | ==================================================== | | OB' %000013 %000001 | __________________________________________________________________________________ Figure B-4. Sample Detailed OCA Report Page 1 ________________________________________________________________________ | | | R E S O L V E D E X T E R N A L P R O C E D U R E S| | | | External references of the program "STICP.SOOL.MPEV". | | Called At Resolved To | | ------------------ ----------- | | Procedure Name Seg Num STT Num LIB | | ===================================================== | | FCONTROL %00000 8 SYSTEM | | | | **** O F F S E T S **** | | | | %000061 | | | | Total Number of calls in segment 0: 1 | | | | Total number of calls to FCONTROL: 1 | | Number of segments which call FCONTROL: 1 | | | | Called At Resolved To | | ------------------ ----------- | | Procedure Name Seg Num STT Num LIB | | ===================================================== | | P'CLOSEIO %00000 5 SYSTEM | | | | **** O F F S E T S **** | | | | %000072 | | | | Total Number of calls in segment 0: 1 | | | | Total number of calls to P'CLOSEIO: 1 | | Number of segments which call P'CLOSEIO: 1 | | | | Called At Resolved To | | ------------------ ----------- | | Procedure Name Seg Num STT Num LIB | | ====================================================== | | P'INITHEAP'3000 %00000 6 SYSTEM | | | | **** O F F S E T S **** | | | | %000016 | | | | Total Number of calls in segment 0: 1 | | | | Total number of calls to P'INITHEAP'3000: 1 | | Number of segments which call P'INITHEAP'3000: 1 | ________________________________________________________________________ Figure B-5. Sample Detailed OCA Report Page 2 ___________________________________________________________________ | | | Called At Resolved To| | ------------------ -----------| | Procedure Name Seg Num STT Num LIB | | =====================================================| | P'RESET %00000 3 SYSTEM | | | | **** O F F S E T S **** | | %000052 | | | | Total Number of calls in segment 0: 1 | | | | Total number of calls to P'RESET: 1 | | Number of segments which call P'RESET: 1 | | | | Called At Resolved To| | ------------------ -----------| | Procedure Name Seg Num STT Num LIB | | =====================================================| | P'REWRITE %00000 4 SYSTEM | | | | **** O F F S E T S **** | | %000035 | | | | Total Number of calls in segment 0: 1 | | | | Total number of calls to P'REWRITE: 1 | | Number of segments which call P'REWRITE: 1 | | | | Called At Resolved To| | ------------------ -----------| | Procedure Name Seg Num STT Num LIB | | =====================================================| | PROCA %00000 7 GROUP | | | | **** O F F S E T S **** | | %000067 | | | | Total Number of calls in segment 0: 1 | | | | Total number of calls to PROCA: 1 | | Number of segments which call PROCA: 1 | | | | Called At Resolved To| | ------------------ -----------| | Procedure Name Seg Num STT Num LIB | | =====================================================| | TERMINATE' %00000 2 SYSTEM | ___________________________________________________________________ Figure B-6. Sample Detailed OCA Report Page 3 _______________________________________________________________________________ | | | **** O F F S E T S **** | | | | %000073 | | | | Total Number of calls in segment 0: 1 | | | | Total number of calls to TERMINATE': 1 | | Number of segments which call TERMINATE': 1 | | | | External references inherited from the group SL (SL.SOOL.MPEV). | | Called At Resolved To | | ------------------ ----------- | | Procedure Name Seg Num STT Num LIB | | ===================================================== | | CREATEPROCESS %00000 2 SYSTEM | | | | **** O F F S E T S **** | | | | %000072 | | | | Total Number of calls in segment 0: 1 | | | | Total number of calls to CREATEPROCESS: 1 | | Number of segments which call CREATEPROCESS: 1 | | | | Called At Resolved To | | ------------------ ----------- | | Procedure Name Seg Num STT Num LIB | | ===================================================== | | FCONTROL %00000 3 SYSTEM | | | | **** O F F S E T S **** | | | | %000032 | | | | Total Number of calls in segment 0: 1 | | | | Total number of calls to FCONTROL: 1 | | Number of segments which call FCONTROL: 1 | | | | P O T E N T I A L I N C O M P A T I L I T I E S | | | | Incompatibilities detected in the program file "STICP.SOOL.MPEV".| | | | FCONTROL: *** System Defined Incompatibility *** | | - Some FCONTROL controlcodes are no longer valid | | on MPE/iX (CM/NM 500). | | These controlcodes include: 03, 48. | | | _______________________________________________________________________________ Figure B-7. Sample Detailed OCA Report Page 4 ________________________________________________________________________________ | | | Incompatibilities detected in the group SL (SL.SOOL.MPEV). | | | | CREATEPROCESS: *** System Defined Incompatibility *** | | - CREATPROCESS may encounter byte pointer problems | | in NM on MPE/iX (NM 107). | | | | FCONTROL: *** System Defined Incompatibility *** | | - Some FCONTROL controlcodes are no longer valid | | on MPE/iX (CM/NM 500 | | These controlcodes include: 03,48. | | | | S U M M A R Y I N F O R M A T I O N | | | | NM Only Incompatibilities: 1 | | CM/NM Incompatibilities: 2 | | Uncallable Procedures Detected: 0 | | | | I N T R I N S I C M E C H A N I S M I N F O R M A T I O N| | | | Applications being recompiled to native mode must use the intrinsic| | mechanism for system intrinsics. | | | | Number of procedures requiring the intrinsic mechanism: 3 | | | | Procedures from STICP.SOOL.MPEV requiring the intrinsic mechanism: | | FCONTROL | | | | Procedures from SL.SOOL.MPEV requiring the intrinsic mechanism: | | CREATEPROCESS FCONTROL | ________________________________________________________________________________ Figure B-8. Sample Detailed OCA Report Page 5