TOCPREVNEXTINDEX

Lund Performance Solutions


The CSEQ Tool
CSEQ reports the calling sequence of intrinsics. The intrinsic may be a Native Mode intrinsic, a Compatibility Mode intrinsic, or both. Also CSEQ can report on user-defined intrinsic files via the SPLINTR or SYSINTR commands.

Operation

CSEQ is used to display Native Mode and Compatibility Mode intrinsic calling sequences as defined by either the SYSINTR or SPLINTR files. The defaults startup condition for CSEQ assumes that the user is interested in reporting on Native Mode intrinsics from SYSINTR.PUB.SYS, AIFINTR.PUB.SYS, PEINTR.PE.SYS, or SPLINTR.PUB.SYS. At that point it is simply a matter of entering the name of the intrinsic for which you are interested. See the sample output provided next for an illustration on how this works.

Native Mode Output

When CSEQ is asked to display the calling sequence of a Native Mode intrinsic, it generates output like following example.


Figure 6.1 Native Mode Intrinsic Calling Sequence
The first line of output means that the intrinsic HPDEBUG is in the SYSINTR file in UPPERCASE. If the procedure name had been reported in lowercase then that would be the exact name of the procedure. When you enter a procedure name in CSEQ, it first tries uppercase and then lowercase automatically.
For HPDEBUG, CSEQ noticed that it was an untyped-procedure. If it had a type (i.e., integer) then it would report it as a function... :integer.
After reporting all of the parameters, CSEQ reports general information about the intrinsic. The intrinsic marked as extensible 2 and uncheckable anyvar. These are explained below:

extensible 2
The intrinsic must be called with at least the first two parameters and the number of actual parameters is passed in as a hidden value in register R26.
uncheckable anyvar
Any parameters declared as anyvar normally have a hidden size parameter passed in just after the actual parameter. Uncheckable anyvar means that no hidden size parameters are passed in. If this intrinsic had not been "uncheckable" then it would have reported the location of the hidden size parameters.

Compatibility Mode Output

When CSEQ is asked to display the calling sequence of a compatibility mode intrinsic, it generates output like the following example.




Figure 6.2 Compatibility Mode Intrinsic Calling Sequence
All Q- addresses are valid as of the start of the intrinsic. Since most parameters are one halfword in size (16-bits), CSEQ doesn’t list their size. Instead, only those parameters that are larger than one halfword are flagged with a size, as in Parm 1 in DASCII.
In the above example, FCHECK is an untyped procedure and DASCII is type integer (returns a 16-bit value). Since DASCII returns a result, the stack storage location for the result is shown.
After all of the parameters, if any, CSEQ reports general information about the intrinsic. FCHECK was marked as "option variable", which means it has a parameter mask at Q-4. Option variable procedures with more than 16 parameters have a two-halfword parameter mask stored at Q-5 and Q-4.

NOTE For some intrinsics, CSEQ displays detailed parameter information. FFILEINFO, for instance, has an additional 100 lines of itemnum information that can be displayed after the normal parameter list information. If you want the itemnum information only, precede the intrinsic name with a plus (+) sign. For example: +ffileinfo

Capabilities

Program capabilities required include IA, BA, DS, and PH. No special user capabilities are required to run CSEQ.

Usage

CSEQ can be run via the supplied UDC or with the MPE RUN statement. CSEQ can accept input through the INFO string parameter or directly from the user in query mode.
  • UDC
  • CSEQ [<commands | [+] intrinsics>]
  • RUN
  • RUN CSEQ.PUB.LPSTOOLS;INFO="[<commands | [+] intrinsics>]"

    Command Summary

    The following table provides a simple description of CSEQ commands that you can use to quickly locate the command that suits the task at hand.

    NOTE Portions of command codes are printed in uppercase to denote the part of the command that CSEQ requires in order to distinguish one command from another.

    Table 6.1 CSEQ Commands
    Command Code
    Description
    ALL
    Lists all matching intrinsics for the current mode (CM, NM or BOTH).
    ALLCM
    Displays all CM intrinsics of a class
    ALLNM
    Displays all NM intrinsics of a class
    BOTH
    Displays both NM & CM intrinsics information
    CLOSE
    Closes a SYSINTR, SPLINTR, or file #
    CM
    Displays CM intrinsic information only
    Exit
    Terminates CSEQ
    HELP
    Invokes CSEQ Help
    NM
    Displays NM intrinsic information only
    SET/REset
    Enables and disables options
    SPLINTR
    Opens an MPE V intrinsics file
    STATUS
    Displays information about currently opened files
    SYSINTR
    Opens an MPE/iX intrinsics file
    //
    Synonym for EXIT
    ?
    Synonym for HELP

    Command Definitions

    This section describes CSEQ commands in detail.

    ALL

    The ALL command provides a means for listing all intrinsics or all intrinsics that have a common prefix. ALL will list all matching intrinsics for the current mode (CM, NM, or BOTH).

    ALLCM

    This command has the following syntax:
    ALLCM [intrinsic name]
    This CSEQ command will display parameter information for the specified class of intrinsics. If an intrinsic name is not specified, then all of the Compatibility Mode intrinsics will be displayed. Partial names can be specified to display a class of intrinsics.

    NOTE The puls (+) option, which displays itemnum information only, is not available for this command, but the minus (-) option, which disables extra information displays is available.

    For example: ALLCM MY could be used to display all of the intrinsics that start with the letters MY.

    ALLNM

    This command has the following syntax:
    ALLNM [intrinsic name]
    This CSEQ command will display parameter information for the specified class of intrinsics. If an intrinsic name is not specified, then all of the Native Mode intrinsics will be displayed. Partial names can be specified to display a class of intrinsics.

    NOTE The puls (+) option, which displays itemnum information only, is not available for this command, but the minus (-) option, which disables extra information displays is available.

    For example: ALLNM HP could be used to display all of the intrinsics that start with the letters HP.

    BOTH

    This command has the following syntax:
    BOTH [intrinsic name]
    The BOTH command tells CSEQ to display the calling sequence for both Native Mode and Compatibility Mode intrinsics.

    NOTE The puls (+) option, which displays itemnum information only, is not available for this command, but the minus (-) option, which disables extra information displays is available.

    After issuing BOTH, entering the intrinsic name ASCII would result in:


    Figure 6.3 BOTH Command Screen

    CLOSE

    This command has the following syntax:
    CLOSE ["sysintr" | "splintr" | <file#>]
    The BOTH command can be used to limit CSEQ's intrinsic file scan. By default (on NM machines) SYSINTR.PUB.SYS, AIFINTR.PUB.SYS, PEINTR.PE.SYS, and SPLINTR.PUB.SYS are scanned. See the STATUS command to determine file numbers <file#> for use with this command.

    CM

    The CM command tells CSEQ that you now want to see the calling sequence for Compatibility Mode intrinsics. If CM is followed by an intrinsic name, it is looked up immediately.

    Exit (or //)

    The Exit command terminates CSEQ.

    HELP (or ?)

    The HELP command invokes the CSEQ help facility.
    Help on a specific command is available by typing:
    ? commandname
    or
    HELP commandname

    NM

    The NM command tells CSEQ that you now want to see the calling sequence for Native Mode intrinsics.

    SET | RESET

    These commands have the following syntaxes:
    SET option
    RESET option
    The SET/RESET commands are used to turn options on or off.
    An option can be set by entering: SET optionname
    An option can be reset by entering: RESET optionname or: SET NOoptionname
    Options are described in the next table:
    Table 6.2 SET / RESET Options
    Option
    Description
    ALLSIZES
    Tells CSEQ to report the size of every parameter, in bits. Normally, CSEQ reports only the sizes of selected parameter types.
    C
    Tells CSEQ that you want to see intrinsic headers in C language style.
    CASEsensitivity
    Tells CSEQ to look for intrinsics in a case sensitive manner. Normally, this should not be necessary.
    CM
    Tells CSEQ you want to see Compatibility Mode intrinsics, not Native Mode (NM) intrinsics.
    CSEQDATA
    Tells CSEQ that the ALLNM command should search the CSEQ.DATA file for extra "intrinsics" (i.e., printf).
    Default: SET CSEQDATA
    EXTRAS
    Tells CSEQ that you want to see extra comments about intrinsics. SET NOEXTRAS suppresses the extra comments.
    Default: SET EXTRAS
    EXTRASONLY
    Tells CSEQ that you want to see only extra comments above intrinsics, and nothing about the actual calling sequence. This is useful for intrinsics with many parameters, like HPFOPEN.
    Default: RESET EXTRASONLY (SET NOEXTRASONLY)
    GCC
    Tells CSEQ that you want to see intrinsic headers in gcc language style.
    LANGuage
    Tells CSEQ to report the language that each NM intrinsic is written in. The language is shown as a number, not as a name.
    Default: RESET LANG (SET NOLANG)
    (because all NM intrinsics report that they are written in Pascal/XL as of MPE/iX 4.0)
    MACRO
    Tells CSEQ to emit a Debug/XL macro to show the parameters of each subsequent intrinsic.
    Default: RESET MACRO
    NM
    Tells CSEQ you want to see Native Mode intrinsics, not Compatibility Mode (CM) intrinsics.
    PARMS
    When reset, tells CSEQ to list only the names of intrinsics, and not any parameters or functional results. This is most useful in conjunction with the ALL command. When set, CSEQ lists the parameters of intrinsics.
    Default: SET PARMS
    PARMTRUNC
    If SET, tells CSEQ that if it sees a parameter name beginning with "...", that it should skip the rest of the parameters for the intrinsic. (As delivered, CSEQ.DATA has two instances of such parameters, in HPFOPEN and HPDEVCREATE.)
    Default: SET PARMTRUNC
    PE
    Tells CSEQ to report addresses of NM intrinsic parameters are relative to the Procedure Exit parameter data structure.
    NOTE Setting PE implicitly does a RESET MACRO.
    PLUSPLUS
    Tells CSEQ that intrinsics with extra documentation are interesting. (Obscure)
    SORT
    Tells CSEQ to sort the list of NM intrinsics found in an ALL command. CM intrinsic names are not sorted.
    Default: SET SORT
    UNNAMED
    Tells CSEQ to only list intrinsics that have no names for their parameters. This is usually used with the ALL command, and is intended as an internal debugging tool.
    Default: RESET UNNAMED

    SPLINTR

    This command has the following syntax:
    SPLINTR filename
    The SPLINTR command tells CSEQ that you now want to look for Compatibility Mode intrinsics in a different intrinsic file. CSEQ opens the specified CM intrinsic file. If the new file cannot be opened, CSEQ will report an error and revert to SPLINTR.PUB.SYS. Also does an implied CM command.
    Example: splintr splintrx.pub.splash Closes the current SPLINTR file (if any) and opens SPLINTR.PUB.SPLASH. Sets mode to CM.

    STATUS

    This command is used to display a small report about which intrinsic files are being used.

    SYSINTR

    This command has the following syntax:
    SYSINTR filename
    The SYSINTR command tells CSEQ that you now want to look for Native Mode intrinsics in a different intrinsic file. CSEQ opens the specified NM intrinsic file. If the new file cannot be opened, CSEQ will report an error and revert to SYSINTR.PUB.SYS. Also does an implied NM command.
    Example 1: sysintr aifintr.pub.sys switches to SYSINTR format file AIFINTR.PUB.SYS. Sets mode to NM.
    Example 2: allnm lists all intrinsics in current sysintr file (AIFINTR.PUB.SYS).

    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".

    CSEQ Examples

    Following are some examples of the information discussed in the previous sections.


    Figure 6.4 CSEQ Output Using the Both Option
    Figure 6.5 shows how CSEQ’s ALLNM command works. If a partial intrinsic name is given, then all intrinsics that match that partial description are displayed. In this example, two intrinsics matched the partial description.


    Figure 6.5 ALLNM Command
    Figure 6.6 shows how the SET PE command affects CSEQ’s NM output. When enabled, this command is used to display an intrinsic’s parameters as offsets from the parameter area of a procedure exit handler.


    Figure 6.6 SET PE Command
    Figure 6.7 shows how to use the status and close commands.


    Figure 6.7 STATUS and CLOSE Commands

    CSEQ Error Messages

    Table 6.3 CSEQ Error Messages
    Message
    Cause
    Action
    CSEQ does not have an open command
    User accidentally typed "open"
    Use SYSINTR filename or SPLINTR filename

    Lund Performance Solutions
    www.lund.com
    Voice: (541) 812-7600
    Fax: (541) 81207611
    info@lund.com
    TOCPREVNEXTINDEX