HP 3000 Manuals HP 3000 Manuals
Using OCA OCA is initiated by running the program file OCA.PUB.SYS either interactively or in batch mode. You can get an explanation of the input expected for any particular prompt by entering a question mark (?). You may also issue any MPE command that can be executed programmatically by prefixing it with a colon (:). After the HELP text is displayed, or the MPE command is executed, the original prompt is redisplayed. A double slash (//) at any prompt causes OCA to terminate. Figure B-1 charts the flow of control for OCA prompts. Additional information on the prompts is provided in subsequent headings. Defaults for all prompts are shown in upper case.Figure B-1. Object Code Analyzer Enable Options Prompt Do you want to enable any options (yes/NO)? This is the first prompt from OCA. You are being asked if you wish to access the two optional features of OCA prior to entering the scanning portion of the program. * A positive response takes you to the User Externals prompt. * A negative response (the default) or a Return * A "//" terminates OCA. Respond Yes only if you need to add user-selected, externally referenced procedures or build an indirect file of file specifications identifying files you want scanned. Scan User Externals Prompt Scan for user selected external procedure references (yes/NO)? OCA scans files for a set of predefined system incompatibilities. You are being asked if you have additional external procedures that you want temporarily added to the set of predefined system incompatibilities detected by OCA: * A positive response indicates that you have additional external procedures that you want OCA to look for and takes you to the Enter External prompt. * A negative response (the default) or a Return indicates that you want OCA only to look for its set of predefined system incompatibilities, and OCA takes you to the next option, the Build Indirect File prompt. * A "//" terminates OCA. When OCA scans program files, user-selected external procedure references are reported if they resolve to any SL. Predefined system incompatibilities are reported only when the procedure resolves to the system library SL.PUB.SYS. If a user-selected procedure name is identical to a predefined incompatible system procedure, then two different messages may be reported. OCA prints a message if you add an external procedure name already in the list. Enter External Prompt Enter external procedure name or indirect file name: You are being prompted for the external procedures that you want added to the events detected by OCA. You can specify system entry points and user-written procedures. The object code scanner looks for references to these external procedures in addition to the set of predefined system incompatibilities that OCA scans. Press Return when you are finished entering procedure names and wish tp proceed to the next prompt The syntax for this prompt is as follows: [external procedure name ] [!indirect file name ] [indirect file name ] All of the external procedure names you enter at this prompt, either directly or via an indirect file, are written to a temporary file named OCAPNAME. If you wish, you can save this file as a permanent file using the MPE V/E :SAVE command and use it as an indirect file on subsequent invocations of OCA. External Procedure Names. OCA accepts a very general, language independent syntax for procedure names. Names are required to start with an alpha character and then can contain any combination of alpha and numeric characters plus the apostrophe (') and underbar (_) characters. OCA returns an error message if the procedure name is syntactically incorrect, and returns the prompt. Because of restrictions in the MPE V Segmenter and the program/SL file format, procedure names are truncated to 15 characters. OCA follows this convention and issues a warning message when a name is over 15 characters in length. External procedure names can be quoted (with either single or double quotes) or unquoted: * Unquoted procedure names are upshifted as is the usual convention on an MPE V/E-based system. * Quoted procedure names are treated as literals and are not upshifted or downshifted. (Use double quotes around procedure names containing imbedded single quotes.) Indirect File Names. As an alternative to entering the names of all your external procedures one at a time, you may specify an indirect file that contains the names of external procedures you wish added to the set of predefined system incompatibilities OCA searches for during the scanning portion of the program. As is the case with all OCA indirect files, the file name must be preceded by either an exclamation point (!) or a percent symbol (%). The indirect file must be an EDIT/V compatible file, numbered or unnumbered, with the following physical characteristics: * Standard file type (the default) * ASCII * Permanent, existing in the system file domain * File code must be 0 (the default) If you respond with an incorrect or nonexistent file name, OCA produces an error message and issues the prompt again. The general format of this file is similar to the format of indirect files described later in this appendix, except that nested indirect files are not allowed at this prompt. The file should contain one procedure name per line (leading and trailing blanks are ignored). The conventions for specifying external procedures are described in "External Procedure Names" above. You can use the string "--" to delineate the rest of the line as a comment that is ignored by OCA. The end of line ends the comment. Blank lines are likewise ignored. In addition, only the first 72 bytes of each record are read by OCA. Everything past column 72 is ignored. Following is an example of the file of procedure names created by OCA: ___________________________________________________________ | | | 5 READ'TAB'1 --comment to end of line | | 6 PROC1 | | 7 | | 8 KEEPTIME | | 9 UPDATE_TAB --comment to end of line | | 10 "Abort'IO" --a quoted procedure name | | 11 'AbortProg' --another quoted procedure name| ___________________________________________________________ Build Indirect File Prompt Build an indirect file of file names (yes/NO)? You are being asked if you want OCA to build a file that contains the MPE file designators of the files you want OCA to scan later during the scan portion of the program. * A positive response to this prompt causes OCA to build an indirect file you can later specify at the SCAN prompt and takes you to the Indirect File Name prompt. * A negative response (the default) or a Return takes you to the SCAN prompt. * A "//" terminates OCA. This "Build Indirect File" feature can be useful if you have a large number of files to scan that are centralized in a few key groups and accounts on the system, and you want to save the set of file names for future use. A second use of this feature is generating a list of the names of programs and SL files to be considered as candidates for migration. Indirect File Name Prompt Enter name for indirect file: You are being prompted for the name of the file you want to associate with the indirect file you are about to create. This file will contain the names of files that you later want OCA to scan during the scanning portion of the program. Valid responses to this prompt are: * A file name following MPE V/E file naming conventions. * A Return takes you to the Scan prompt. * A "//" terminates OCA. If you specify a valid MPE file name and press Return, creates and opens a new file with the name you specified at the prompt, then proceeds to the "Enter File specification" prompt (described below.). Enter File Specification Prompt Enter file specification: You are being prompted for the information to include in the indirect file you just created. The indirect file is used to specify the files to be scanned in response to the SCAN prompt and is helpful in identifying program and SL files from generic file sets. Each line of the indirect file will be treated by the SCAN prompt as if you had entered it interactively (in other words, as a command image). Thus, the indirect file can contain any valid response to the SCAN prompt. After OCA has opened the indirect file, it repeatedly prompts you for files or file sets to be scanned. The file set specifications may include wild cards. OCA automatically selects all program and SL files residing in the file set. The fully qualified names of individual program and SL files are written to the indirect file. Press Return when you are finished entering file specifications and wish to proceed to the next prompt. Once you have entered the contents of the indirect file, OCA attempts to close the indirect file as a permanent file. If a file of the same name already exists in the permanent file directory, OCA asks you if the old file should be purged. If you respond YES, OCA purges the old file before it closes the indirect file. If you respond NO to the purge request (or press Return), OCA asks if you want to save the file under a different name. If you respond NO to this prompt (or press Return), the indirect file you just built is lost. If you respond YES, you are prompted for a different name for the indirect file you just built. If you press Return in response to the prompt for a different name, the indirect file you just built is lost. In both cases where the file is lost, OCA returns you to the Indirect File Name prompt and allows you to create a new indirect file. When you succeed at saving the indirect file, OCA takes you to the SCAN prompt. The syntax for the Enter File Specification prompt is: file specification [library specification] [report level] [report destination] The syntax for the required file specification is: { filename } { fileset } { !indirect filename } { #indirect filename } The syntax for the optional library specification is: { GROUP } [; LIB = { PUBLIC } ] { SYSTEM } The syntax for the optional report level is: [; DETAILED ] [; BRIEF ] The syntax for the optional report destination is: [; OFFLINE ] As a convention OCA keywords are shown in upper case, although you do not have to enter them in upper case on the command line. In addition, only the minimum number of characters necessary to recognize the keyword must be specified. For example, ;DETAILED can be entered as ;DET or as ;D.
NOTE Each line of the indirect file is treated as a command image at the SCAN prompt. Therefore, the syntax and meaning of the options listed above are identical to the optional parameters available throughout the SCAN prompt.
Details of the file specification, library specification, report level, and report destination parameters are discussed below. File Specifications. OCA scans only MPE V/E format SL or program files. You can specify the files you want placed in the indirect file in the following ways: * By file name * By file set * By indirect file name By File Name. You can enter the name of a single program or SL file. OCA displays an error message if the file is not of the correct type. Program and SL files are treated slightly differently; the differences are reflected only in the detailed report. By File Set. You can enter a file set. You can select groups of program and/or SL files using MPE wild card characters (@, #, ?) in conjunction with file designators. OCA searches the specified file set and includes in the indirect file the fully qualified file designators of only the program and SL files located in the specified file set. For example, if you specify @.mygroup.myacct, OCA places in the indirect file all program and SL files located in group mygroup, account myacct.
NOTE The file set specification can contain MPE wild card characters (@, #, ?) except that OCA interprets the single question mark followed by a space or Return as a request for OCA HELP facility instead of as a wild card character. Therefore, if you want to specify all single-character file names, you must use a more qualified file specification, for example: ?.mygroup ?.mygroup.myacct
By Indirect File Name. You can enter the name of an indirect file that you have previously created either by the Build Indirect File option of OCA or from an editor. As is the case with all OCA indirect files, the file name must be preceded by either a ! or a %. The indirect file must be an EDIT/V compatible file, numbered or unnumbered, with the following physical characteristics: * Standard file type (the default) * ASCII * Permanent, existing in the system file domain * File code must be 0 (the default) If you respond with an incorrect or nonexistent file name, OCA produces an error message and issues the prompt again. The general format of this file is similar to the format of indirect files described earlier in this appendix, except that indirect files of file specifications can be nested up to five levels deep. The file should contain one command per line (following the syntax described above). Leading and trailing blanks are ignored. Use the string "--" to delineate the rest of the line as a comment that is ignored by OCA. The end of line ends the comment. Blank lines are likewise ignored. In addition, only the first 72 bytes of each record are read by OCA (everything past column 72 is ignored). Following is an example of the contents of an indirect file of file specifications: _________________________________________________________ | | | 1 EOMRPT;LIB=G | | 2 SCRNDVR.PUB.DRIVERS --comment to end of line | | 3 @.PUB.OURSYS;DETA | | 4 ZEDIT;BRIEF;OFFLINE | | 5 !INDIRECT.PUB.MYACCT;BRIEF --an indirect file| _________________________________________________________
NOTE The additional options you specify with the indirect filename option will override whatever options may have been specified within that indirect file. In the example above, specification of the ;BRIEF option for the indirect file !INDIRECT.PUB.MYACCT overrides any specifications for a detailed report format that may be made within !INDIRECT.PUB.MYACCT.
LIB= Option. The LIB= option tells OCA what system libraries the loader would search if the specified program file were to be loaded. It is interpreted in exactly the same way as the LIB= option on the MPE V/E :RUN command. The default library indicator is "S". Specifying LIB=S is equivalent to omitting the LIB= option entirely. The LIB= option should be specified only with program files. If you specify LIB with an SL file, the LIB= parameter is ignored. When the LIB= option is used with a file set or with an indirect file, the specified library is applied to those files in the file set (or in the indirect file) that are program files and is ignored for the SL files. If you request that a file is to be scanned LIB=G or LIB=P and a group or account SL does not exist, OCA does not print an error message. This is consistent with the behavior of the MPE V/E :RUN command. However, the OCA detailed report notes when an SL is not required. OCA always tells you which SL file the external procedure will actually be resolved to when the program is loaded. It also tells you if you specified a group or account SL and none of the externals resolved to the group or account SL specified. This information is useful for determining which SLs are needed (and not needed) for migration.
NOTE If you request that an SL file is to be scanned, OCA scans the entire SL file. If you request that a program file be scanned the LIB= option, OCA scans only the segments that contain external procedures directly referenced by the program, or indirectly referenced by externals of SL segments.
Brief and Detailed Options. By default, OCA produces a report on file specification in a brief format that provides only information directly related to migrating the program file successfully, including names of external procedures that have been identified as incompatibilities for the purposes of migration. Specifying ;BRIEF with a file name or file set is the same as not specifying ;BRIEF. You can optionally specify ;DETAILED if you want much greater detail about all of file specification's externally referenced procedures. In addition, the ;DETAILED option produces general information about the program structure of file specification. Specifying either the ;BRIEF or the ;DETAILED option with an indirect file overrides all uses of this option that may be found within that indirect file. Offline Option. By default, OCA output is directed to the job/session list device $STDLIST. If you use the ;OFFLINE option, you direct OCA 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 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> | ___________________________________________ SCAN Prompt SCAN> You are being prompted for the name of the file(s) you want OCA to scan for incompatibilities. Valid responses to this prompt are: * A file specification (with optional keyword parameters), following the syntax description described below. * Return, which returns you to the SCAN prompt. * A "//", which terminates OCA. A report is generated for each file scanned, and you are prompted for the name of the next file to scan. If a file set has been specified, OCA displays progress messages indicating the start of the directory search and the number of program and SL files found. OCA always displays the name of the file being scanned. Normally, OCA automatically checks the files against a set of predefined system incompatibilities located in the file OCAINCOM.PUB.SYS. Optionally, a set of user-selected incompatibilities created by the Build Indirect File option temporarily disables access to OCAINCOM.PUB.SYS by using a file equation to equate OCAINCOM.PUB.SYS to $NULL prior to executing OCA. You can later invoke the :RESET command to enable OCAINCOM.PUB.SYS. Following is a sequence of SCAN prompt entries where this is accomplished: _____________________________________ | | | :FILE OCAINCOM.PUB.SYS=$NULL | | :RUN OCA.PUB.SYS | | :SCAN>// | | :RESET OCAINCOM.PUB.SYS | _____________________________________ The syntax for the SCAN prompt is: file specification [library specification] [report level] [report destination]'' The syntax for the required file specification is: { filename } { fileset } { !indirect filename } { #indirect filename } The syntax for the optional library specification is: { GROUP } [; LIB = { PUBLIC } ] { SYSTEM } The syntax for the optional report level is: [; DETAILED ] [; BRIEF ] The syntax for the optional report destination is: [; OFFLINE ] As a convention, OCA keywords are shown in upper case, although you do not have to enter them in upper case on the command line. In addition, only the minimum number of characters necessary to recognize the keyword must be specified. For example, ;DETAILED can be entered as ;DET or as ;D. If you specify the file name EXIT (or any of its substrings EXI, EX, E) and a file by that name does not exist in the current logon group, OCA terminates. To be safe, qualify EXIT (or its substring) with the group name (for example, EXI.MYGROUP). Details on the file specification, library specification, report level, and report destination parameters are discussed below. File Specifications. OCA scans only MPE V/E format SL or program files. You can specify the files you want scanned in the following ways: * By file name * By file set * By indirect file name By Filename. You can enter the name of a single program or SL file. OCA displays an error message if the file is not of the correct type. Program and SL files are treated slightly differently. The differences are reflected only in the detailed report. By File Set. You can enter a file set by selecting groups of program and/or SL files using MPE wild card characters (@, #, ?) in conjunction with file designators. OCA searches the specified file set and scans only the program and SL files located in the specified file set. For example, if you specify @.mygroup.myacct, OCA scans all program and SL files located in group mygroup, account myacct.
NOTE The fileset specification can contain MPE wild card characters (@, #, ?), except that OCA interprets the single question mark followed by a space or Return. Therefore, if you want to scan single-character file names you must use a more qualified file specification, for example: ?.mygroup ?.mygroup.myacct
By Indirect File Name. You can enter the name of an indirect file that you have previously created either by the Build Indirect File option of OCA or from an editor. As is the case with all OCA indirect files, the file name must be preceded by either a ! or a %. The indirect file must be an EDIT/V compatible file, numbered or unnumbered, with the following physical characteristics: * Standard file type (the default) * ASCII * Permanent, existing in the system file domain * File code must be 0 (the default) If you respond with an incorrect or nonexistent file name, OCA produces an error message and issues the prompt again. The general format of this file is similar to the format of indirect files described earlier in this appendix. Indirect files of file specifications can be nested up to five levels deep. The file should contain one file specification per line (following the syntax described above). Leading and trailing blanks are ignored. You can use the string "--" to delineate the rest of the line as a comment that is ignored by OCA. The end of line ends the comment. Blank lines are likewise ignored. In addition, only the first 72 bytes of each record are read by OCA. (Everything past column 72 is ignored.) Following is an example of the contents of an indirect file of file specifications: ______________________________________________________________________ | | | 1 EOMRPT;LIB=G | | 2 SCRNDVR.PUB.DRIVERS --comment to end of line | | 3 SCRAMBLE.PUB.OURSYS | | 4 ZEDIT;BRIEF;OFFLINE | | 5 !FILESPECS.PUB.MYACCT;DETAILED --an indirect file| ______________________________________________________________________
NOTE The additional options you specify with the indirect file name option at the SCAN prompt will override whatever options that may have been specified within that indirect file. For example, if you specify at the SCAN prompt the indirect file described above with the ;BRIEF option, the contents of the file set @.PUB.OURSYS and the contents of the indirect file !FILESPECS.PUB.MYACCT will be reported in the brief report format.
LIB= Option. The LIB= option tells OCA what system libraries would be searched if the program file were to be loaded. It is interpreted in exactly the same way as the LIB parameter on the MPE V/E :RUN command. The default library indicator is "S". Specifying LIB=S is equivalent to omitting the LIB= parameter. The LIB= option should be used only if scanning a program file. If you specify LIB= with an SL file, the LIB= parameter is ignored. When the LIB= option is used with either a file set or an indirect file, the specified library is applied to those files in the file set (or in the indirect file) that are program files, and ignored for the SL files. If you request that a file is to be scanned LIB=G or LIB=P and a group or account SL does not exist, OCA does not print an error message. This is consistent with the behavior of the MPE :RUN command. The OCA detailed report, however, notes when an SL is not required. OCA always tells you which SL file the external procedure will actually resolve when the program is loaded. It also tells you if you specified a group or account SL and none of the externals would resolve to the group or account SL specified. This information is useful for determining which SLs are needed (and not needed) for migration.
NOTE If you request that an SL file is to be scanned, OCA scans the entire SL file. If you request that a program file be scanned with the LIB parameter, OCA scans only the segments that contain external procedures directly referenced by the program, or indirectly referenced by externals of SL segments.
Brief and Detailed Options. By default, OCA produces a report on file specification in a brief format that provides only information directly related to the ability of the program file to migrate successfully, including names of external procedures that have been identified as incompatibilities for the purposes of migration Specifying ;BRIEF with a file name or file set is the same as not specifying ;BRIEF. You can optionally specify ;DETAILED if you want much greater detail about all of file specification's externally referenced procedures. In addition, the ;DETAILED option produces general information about the program structure of file specification. Specifying either the ;BRIEF or the ;DETAILED option with an indirect file overrides all uses of this option that may be found within that indirect file. Offline Option. By default, OCA output is directed to the job/session list device $STDLIST. If you use the ;OFFLINE option, you direct OCA 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 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> Interactive Pagination When using OCA interactively and the report fills one page on your screen, OCA displays the More prompt. OCA does not display the More prompt when run from batch mode. More (YES/no/all)? The following responses are valid to the More prompt: * YES (the default) tells OCA that you want to continue listing the text. OCA will display the More prompt each time it fills one page on your screen. * NO tells OCA that you do not want to see the rest of the text. OCA stops scanning any other files specified, and returns you to the SCAN prompt. * ALL tells OCA that you want to see all of the report without intervening More prompts. OCA uses two session level job control words (JCWs) to control page length for output (help text or reports). If OCA determines that the output destination is offline then OCA will use the JCW OCAPAGESIZE to determine the number of lines per page. This would be the case if you specified ;OFFLINE on the command line, or OCA was being run from a :JOB. If the output destination is your terminal screen, OCA will use the OCASCREENSIZE JCW. If these JCWs do not exist or are set to values out of range, OCA will use default values for the page size. If the appropriate JCW is set to zero, then the paging mechanism is disabled. Below are the default values and legal ranges for each of the JCWs described above: * For JCW OCASCREENSIZE, default value is 23; legal range is 0, 1...100 * For JCW OCAPAGESIZE, default value is 60; legal range is 0, 5...100 Exiting OCA Entering a double slash (//) at any prompt terminates OCA. Additionally, if you specify EXIT (or any of it's substrings EXI, EX, E) at the SCAN prompt, or if EXIT is encountered in an indirect file, and a file by that name does not exist in the current logon group, OCA terminates. Security Considerations There are no special restrictions on who can run OCA. OCA, however, places restrictions on which files may be scanned. You must have READ access to the file to scan it. In addition, you must provide lockwords for files requiring them. Users possessing Account Manager capability may scan any file residing in their accounts without specifying the lockword. Similarly, system manager capability allows all files on the system to be scanned without specifying the lockword. Access restrictions, however, may prevent you from scanning a file despite your capabilities. In most cases, if you can run the program, you can scan it. Running OCA in Batch Mode Figure B-2 illustrates how you can use a job stream file to invoke OCA in batch mode. Example B1 shows all the major operations available through OCA.PUB.SYS. Note how MPE V/E commands are executed and then control is returned to the same OCA prompt. In addition, the string "--" indicates to OCA that the remainder of the input line is a comment. Because OCA deletes these comments from the input line before parsing occurs, the comments can be included on MPE V/E command execution lines (see OCA invocation of :FILE command). ______________________________________________________________________________________ | | | :job ocajob, manager.sys | | :run oca.pub.sys | | y | | y -- want to enable some options | | procedure1 -- want to add user selected externals | | procedure2 -- enter the names of some procedures you | | procedure3 -- want to add to predefined list of system | | procedure4 -- incompatibilities | | procedure5 | | -- blank line indicates no more procedure names | | :comment save the procedure names entered above for later use | | :save ocapname | | y -- want to build an indirect file | | indirect -- call the file indirect | | @.@.finance -- get all programs/SLs in finance account | | @.tools.@;lib=g -- get all tools groups in all accounts ;LIB=G | | -- blank line to indicate no more filesets | | -- blank line to indicate no more indirect files| | | | -- We are at the Scan >prompt now, blank lines or comment have no effect. | | -- We are going to do a :showtime before and after we generate the | | -- report just so we can tell how long it took. | | :showtime | | :file ocalist;dev=epoc --direct output to epoc printer | | !indirect;brief;offline --scan the indirect file created above | | :showtime | | // --terminates OCA | | :eoj | ______________________________________________________________________________________ Figure B-2. Job Stream to Execute OCA