TOCPREVNEXTINDEX

Lund Performance Solutions

The ACAP Tool
The ACAP tool is used to view and alter the capabilities and attributes of both native mode and compatibility mode program files. ACAP also displays informational messages that help you identify program capability sets that seem unusual. For example, ACAP will warn you if a program’s NMSTACK is set to zero.
Almost any program file attribute ca be altered or viewed with ACAP, including the status of the OCT flag for compatibility mode programs.

Operation

The most typical use for ACAP is adding a capability to a program file that was omitted during the LINK or PREP stage. This is easily accomplished in a single command line specification (or through an interactive dialogue sequence). Other typical uses include changing the initial value of the stack, heap or testing program operation base of capabilities.
Usually when ACAP is run it will open a program file with read/write access. However, if you don’t have write-access to the file, you may choose to use ACAP’s "PEEK" command and just display the program’s current capability and attribute lists.
When ACAP is used in an interactive dialogue mode, all user changes are written to the program file as soon as the user closes the program file or exits the program. However, if during the course of changing a program file you decide to abandon your changes, you may enter the command "CAP=OLD", and all previously entered changes will be abandoned.

Capabilities

Program capabilities required include IA, BA, DS, MR, PH, PM.

Usage

ACAP can be started from the supplied UDC or from a fully-qualified RUN statement. Another option is to pass commands through the INFO string parameter. For MPE/iX users, progfile can be either a POSIX or MPE file reference.
  • UDC
    • :ACAP [<progfile> [<commands>]]
  • RUN
    • :RUN ACAP.PUB.LPSTOOLS;INFO=“[<progfile> [<commands>]]”

    Command Summary

    The following list provides a simple description of ACAP commands that you can use to quickly locate the command that suits the task at hand. Detailed information on each command is provided in the next section.

    NOTE Portions of the command codes are printed in uppercase to denote the part of the command that ACAP requires in order to distinguish one command from another. However, the commands themselves are not case-sensitive.


    Table 3.1 ACAP Commands
    Command Code
    Description
    CAPability
    Alters program capabilities
    noCHECKS
    [re]Sets parameter checking for programs
    CLose
    Closes program file
    DLsize
    Sets the CM DL size
    DUMPWORTHY
    Resets or sets the DUMPWORTHY bit for native mode programs
    Exit
    Terminates program
    noFATAL
    [re]Sets FATAL error bit for compatibility mode programs
    HELP
    Invokes ACAP help
    Look
    Synonym for Peek
    MAXDATA
    Sets the compatibility mode MAXDATA size
    MAXPRIority
    Sets the MAXPRIORITY field for native mode programs
    nmHEAP
    Sets the native mode Heap size (bytes)
    nmSTACK
    Sets the native mode stack size (bytes)
    noNONFATAL
    [re]Sets NONFATAL error bit for compatibility mode programs
    OCTcomp
    Turn on/off OCT’ed flag for compatibility mode programs
    ODD
    Displays unusual (odd) info about prog
    Open
    Opens a program [edits it]
    Peek
    Displays information about programfile
    noPRIVSEGs
    [re]Sets privileged segments bit for compatibility mode programs
    PRIority
    Sets the PRIORITY field for native mode programs
    STACK
    Sets the compatibility mode or native mode stack size
    noZERODB
    [re]Sets the ZERODB flag for compatibility mode programs

    NOTE The leading "no" is optional. Commands may be abbreviated to the uppercase characters shown (i.e., LOOK or LOO or LO or L).

    Command Definitions

    Listed below are detailed descriptions of the ACAP commands.

    CAPability

    The CAPability command has the following syntax:
    CAPability [+,-,=] <caplist>
    This command is used to alter the capabilities of a program. It uses a very flexible syntax so capability modifications can easily be performed. The CAP command can be used to add (+), subtract (-), or set (=) capabilities to a program. For example, to add PM to a program, type "CAP + PM". Similarly, to remove PM from a program type: "CAP - PM".

    <caplist>
    Can be any of the following: NONE, ALL, OLD, IA, BA, DS, PH, MR, PM separated by commas, + or -. Two non-standard capabilities appear in the caplist above: ALL and OLD. The capability "ALL" tells ACAP to assign all possible capabilities to a program. The "OLD" capability tells ACAP to restore the program’s caplist to its previous state. "NONE" specifies no capabilities.
    NOTE The OLD capability is only valid during a continuous session with a single program.
    [+,-,=]
    Specifying "+" and a capability adds that capability to the open program.
    "-" will subtract a capability.
    Specifying "=" will turn off all capabilities and then add the ones following the "=".

    CLose

    The CLOSE command closes the currently open program file. An implicit CLOSE is done by the EXIT and OPEN commands.

    NOTE ACAP does not allow the renaming of the output filename, so you may want to make a backup copy beforehand. For example, you may want to have two versions of the same program, one with PM and one without. In this case you may want to name one “MYPROG” and the other "MYPROGPM" (hint—use REP in the System Manager’s Toolbox to make a spare copy of MYPROG and name it MYPROGPM. Then use ACAP to add PM to MYPROGPM).

    DLsize

    This command has the following syntax:
    DLsize = #halfwords | *
    The DL (Data Limit) command changes the size of the DL size your program will have the next time it runs. A value of "*" means: restore the DLsize to the value it was when ACAP opened the program file.
    This command is valid only for compatibility mode programs.

    DUMPWORTHY

    This command has the following syntax:
    DUMPWORTHY ON | OFF
    The DUMPWORTHY OFF command resets the DUMPWORTHY flag in the file system for your program file.
    The DUMPWORTHY ON command sets the DUMPWORTHY flag in the file system for your program file.
    In theory, any program file with the DUMPWORTHY flag set should be included in any memory dump generated by the system.

    EXIT (or //)

    The EXIT command is used to terminate ACAP. // is accepted as a synonym.

    FATAL | NOFATAL

    The two forms of this command are used to either set or reset the FATAL bit for compatibility mode programs.

    nmHEAP

    The HEAP command has the following syntax:
    nmHEAP=#bytes | *
    The HEAP command changes the size of the Native Mode Heap your program will have the next time it runs. A value of -1 means that the system default (set via SYSGEN) will be used. A value of "*" means that original value (at ACAP OPEN time) will be restored.
    This command is only valid for native mode programs.

    HELP or ?

    This command has the following syntax:
    HELP [commandname]
    The HELP command with no parameters displays general help about ACAP. Help on a specific command is available by typing: HELP commandname.
    Example: HELP CAP

    LOOK

    The LOOK command has the following syntax:
    LOOK programfilename
    This command is a synonym for Peek. The LOOK command opens the specified program file, reports the values of various attributes, and then closes the file.

    MAXDATA

    The MAXDATA command has the following syntax:
    MAXDATA=#halfwords | *
    The MAXDATA command changes the size of the MAXDATA your program will have the next time it runs. A value of -1 means that the system default (set via SYSGEN) will be used. A value of "*" means that original value (at ACAP OPEN time) will be restored.
    This command is valid only for compatibility mode programs.

    MAXPRIority

    The MAXPRIority command has the following syntax:
    MAXPRIority=# | *
    This sets the MAXPRIORITY field of an NM Program file to the specified value (in the range 0...255).
    A value of "*" means that original value (at ACAP OPEN time) will be restored.
    The affect of this field is not yet known.

    NONFATAL | NONONFATAL

    The two forms of this command are used to either set or reset the NONFATAL bit for compatibility mode programs.

    OCTcomp

    The OCTcomp command has the following syntax:
    OCTcomp <on | off | # | old | *>
    OCTcomp OFF tells ACAP to turn off the flag in the header of a CM program file that marks it as having been OCT'ed (i.e.: run through the OCTCOMP "compiler"). If the program had OCT data available, then ACAP will report it as being "CM (OCT'ed/disabled)". If the program had no OCT data, then it will continue to be reported as simply "CM".
    OCTcomp ON tells ACAP to turn on the OCT'ed flag. ACAP will refuse to turn on the flag if no OCT information is available in the program file.
    OCTcomp # forces the OCT flag word in a CM program file header to the specified value. This command should not be used unless you know exactly what you are doing.
    OCTcomp OLD restores the OCT setting to it's original value for the current ACAP process. An asterisk ("*") can be used as a synonym for OLD.

    ODD

    The ODD command has the following syntax:
    ODD [#] programfilename
    The ODD command opens the specified program file, looks at the values of various attributes, and reports them in a somewhat fixed-format manner *only* if one or more of them are "odd" (or "unusual"). The file is then closed.
    The primary purpose of ODD is to provide the ability to "scan" a group of program files (with multiple ODD commands, one per line), looking for unusual items (i.e.: NMSTACK or NMHEAP with default values).
    If a number is specified before the program file name, then it is interpreted as a bitmask defining which unusual items you want to see. If the number is omitted, -1 (all bits on) is used.

    Bit 15 1
    show NMSTACK or NMHEAP values that are "default".
    Bit 14 1
    show program files with non-zero MAXPRIority or PRIORITY values.
    Bit 13 1
    show program files with the POSIX flag.


    NOTE Default values for NMSTACK and/or NMHEAP are "bad" because the programmer is relying on the system's particular configuration to provide the NMSTACK and/or NMHEAP size. The system manager generally has no idea what that value should be ... it is the responsibility of the programmer to LINK their NM Programs with appropriate NMSTACK and NMHEAP values.

    Open

    The OPEN command has the following syntax:
    Open programfilename [editcommands]
    This command tells ACAP to open the specified NM or CM program file. If [editcommands] are present, they are executed. Editcommands may also be entered on subsequent input lines, until the program file is closed.
    Example:
    OPEN GRANT.PUB.LPSTOOLS
    Example:
    O GRANT.PUB.LPSTOOLS - BA
    The above command opens GRANT.PUB.LPSTOOLS and deletes BA capability.

    Peek

    The Peek command has the following syntax:
    Peek programfilename
    Peek is used to display information about program file when ACAP has READ-only access to that programfilename.

    PRIority

    This command has the following syntax:
    PRIority # | *
    This set the PRIORITY field of an NM Program file to the specified value (in the range 0..255).
    A value of "*" means that original value (at ACAP OPEN time) will be restored.
    The affect of this field is not yet known.

    PRIVSEGs | NOPRIVSEGs

    The two forms of this command are used to either set or reset the PRIVSEG bit for the compatibility mode programs.

    SET | RESET

    SET/RESET are used to set/reset global options within ACAP.
    Options are:
    [NO]CHECKS
    If CHECKS is set (default), then ACAP checks that the values of stack, heap, and DL are reasonable.
    [NO]DEFaults
    DEFaults, if set, causes some ACAP output to be generated in a a fixed-field manner, suppresses all of the capability flags except PM, and reports NM STACK and NM HEAP sizes as "DEFAULT" if they are -1 and 0, respectively. This option is of little use by itself, but can be useful when "LOOK"ing at a large number of program files. NODEFAULTS is set by default.

    STACK

    The STACK command has the following syntax:
    STACK=#elements
    The STACK command changes the size of the Stack your program will have the next time it runs. A value of -1 means that the system default (set via SYSGEN) will be used. The #elements are bytes for a NM program, halfwords for a CM program.

    ZERODB | NOZERODB

    This sets (or resets) the ZERODB bit in a CM program file. ZERODB tells the loader to initialize the primary DB area of a process to all binary zeros at the start of the process.
    It isn't clear if NOZERODB has any affect on MPE/iX.

    TOOLBOX STANDARDS

    The ToolBox collections from Lund Performance Solutions have a uniform user interface. As a result, in addition to the commands specific to each Toolbox tool, most tools allow the commands described in "TOOLBOX STANDARDS".

    ACAP Examples

    This section provides some examples of the various ACAP commands and their syntax. We have also includes examples of actual ACAP screens to help you see more clearly what your screen should look like.
    The screen that follows shows how to add PM capability to a program (called sosimage) in a single command line specification.


    Figure 3.1 Adding PM Capability
    The [<editcommands>] shown on the OPEN command is simply any combination of CAPability commands.
    For example:
    OPEN FOO CAP + PM
    If ACAP is run with an INFO string, then it is interpreted as the one of the following two scenarios:
    OPEN infostring
    EXIT
    or:
    OPEN infostring
    An EXIT command is implied if the infostring contains anything after the program name.
    Thus, a UDC could be written that would give PM capability to a program with no user interaction:
    givepm prog
    run acap.pub.lpstools;info="!prog cap + pm"
    ************
    The automatic EXIT command after the INFO string can be suppressed by running ACAp with PARM=1.
    This can be summarized by the following examples:

    run acap;info="FOO"
    Opens FOO, stays alive
    run acap;info="FOO+PM"
    Opens FOO, adds PM, exits
    run acap;info="FOO+PM";parm=1
    Opens FOO, adds PM, stays alive
    run acap
    Stays alive

    When ACAP runs it prompts with either "ACAP:" or "[programname] ACAP:" (if a program file has been opened).

    NOTE MPE/iX 4.5 users have the option of using POSIX file references.

    Figure 3.2 demonstrates the use of ACAP’s Peek and OCT commands.


    Figure 3.2 Peek and OCT Commands
    In ACAP you have the ability to enter multiple commands on a single line. In this example, the PM and PH capabilities, and NM stack size are all altered in a single command.


    Figure 3.3 Multiple Commands on a Single Line

    ACAP Error Messages

    Each ACAP error message is described in the following table.
    Table 3.2 ACAP Error Messages
    Message
    Cause
    Action
    DL value less than -1 may cause problems
    User entered a value for DL that is less than -1.
     
    Currently, values less than -1 have no known value. Since a value of -1 is used to designate the system default, it was decided to allow other negative values, in the event that HP decides to assign meaning to other negative values.
    Error reading file system information
    ACAP could not obtain file information about the program the user specified.
    For an undetermined reason, the ’ffileinfo’ to the program file failed. Exit ACAP and check the condition of the program file. Make sure that it is a valid program, and that you have the capability to alter it.
    Error reading record #0 of NMPRG file
    ACAP could not obtain the program header information.
    For an undetermined reason, the ’freaddir’ to the program file failed. Exit ACAP and check the condition of the program file. Make sure that it is a valid program, and that you have the capability to alter it.
    Expected a capability
    User entered "CAP=" without giving a new value for CAP.
    The valid capabilities are: BA, IA, PM, MR, DS, PH, OLD, ALL, NONE. If the user wants to alter the capabilities one of the above must be selected. The capabilities cannot be abbreviated, although they are not case-sensitive.
    Expected DL value
    User entered "DL=" without giving a new value for DL.
     
    In order to modify DL, the user must enter a command in the form of "DL=##" where ## is the new value for DL. A value of "-1" is used to designate the system’s default value for this variable.
    NOTE DL can only be modified for compatibility mode programs, filecode=PROG.
    Expected MAXDATA value
    User entered "MAXDATA=" without giving a new value for MAXDATA.
     
    In order to modify the compatibility mode maxdata that a program will use, the user must enter a command of the form "MAXDATA=#" where # is the new value for the compatibility mode MAXDATA. A value of "-1" is used to designate the system’s default value for this variable.
    NOTE MAXDATA can only be modified for compatibility mode programs, filecode=PROG.
    Expected nmHEAP value
    User entered "HEAP=" without giving a new value.
     
    In order to modify the native mode heap size that a program will use, the user must enter a command of the form "HEAP=##" where ## is the new value for the native mode HEAP. A value of "-1" is used to designate the system’s default value for this variable.
    NOTE HEAP can only be modified for native mode programs, filecode=NMPRG.
    Expected OCT FLAGS value
    User entered "OCT" without an option specified.
    Valid options for the "OCT" command are ON, OFF, #, OLD where # denotes a number.
    Expected STACK value
    User entered "STACK=" without giving a new value.
     
    In order to modify the stack size (in either native mode or compatibility mode) that a program will use, the user must enter a command of the form "STACK=#" where # is the new value for the stack. A value of "-1" is used to designate the system’s default value for this variable.
    NOTE STACK can be modified for both native mode programs and compatibility mode programs.