VMS Help System Services, $FORMAT AUDIT  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Converts a security auditing event message from binary format to
    ASCII text.

    Format

      SYS$FORMAT_AUDIT  fmttyp ,audmsg ,[outlen] ,outbuf ,[width]

                        ,[trmdsc] ,[routin] ,[fmtflg]

    C Prototype

      int sys$format_audit  (unsigned int fmttyp, void *audmsg,

                            unsigned short int *outlen, void *outbuf,

                            unsigned short int *width, void *trmdsc,

                            int (*routin)(__unknown_params), unsigned

                            int fmtflg);

1 - Arguments

 fmttyp

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Format for the message. The fmttyp argument is a value indicating
    whether the security audit message should be in brief format,
    which is one line of information, or full format. The default
    is full format. Refer to the OpenVMS System Manager's Manual for
    examples of formatted output.

    The following table defines the brief and full formats:

    Value                  Meaning

    NSA$C_FORMAT_STYLE_    Use a brief format for the message.
    BRIEF
    NSA$C_FORMAT_STYLE_    Use a full format for the message.
    FULL

 audmsg

    OpenVMS usage:char_string
    type:         byte stream (unsigned)
    access:       read only
    mechanism:    by reference
    Security auditing message to format. The audmsg argument is
    the address of a buffer containing the message that requires
    formatting.

 outlen

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference
    Length of the formatted security audit message. The outlen
    argument is the address of the word receiving the final length
    of the ASCII message.

 outbuf

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor
    Buffer holding the formatted message. The outbuf argument is
    the address of a descriptor pointing to the buffer receiving the
    message.

 width

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference
    Maximum width of the formatted message. The width argument is the
    address of a word containing the line width value. The default is
    80 columns.

    The width argument does not work consistently. In most cases, if
    you specify both the width argument and the full format style
    (NSA$C_FORMAT_STYLE_FULL), $FORMAT_AUDIT ignores the width
    argument. The minimum width is 80 columns; lower values do not
    limit the width to less than 80. If you specify a width greater
    than 80 columns, most lines are not joined to use the full width.

    In most cases, you should avoid using the width argument.

 trmdsc

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor
    Line termination characters used in a full format message. The
    trmdsc argument is the address of a descriptor pointing to the
    line termination characters to insert within a line segment
    whenever the width is reached.

 routin

    OpenVMS usage:procedure
    type:         procedure value
    access:       read only
    mechanism:    by reference
    Routine that writes a formatted line to the output buffer. The
    routin argument is the address of a routine called each time a
    line segment is formatted. The argument passed to the routine
    is the address of a character string descriptor for the line
    segment.

    When an application wants event messages in the brief format,
    $FORMAT_AUDIT calls the routine twice to format the first event
    message. The first time it is called, the routine passes a string
    containing the column titles for the message. The second and
    subsequent calls to the routine pass the formatted event message.
    By using this routine argument, a caller can gain control at
    various points in the processing of an audit event message.

 fmtflg

    OpenVMS usage:longword (unsigned)
    type:         mask_longword
    access:       read only
    mechanism:    by value
    Determines the formatting of certain kinds of audit messages.
    The fmtflg argument is a mask specifying whether sensitive
    information should be displayed or column titles built for
    messages in brief format. For example, the operating system
    uses bit 0 to suppress plain-text passwords from security alarm
    messages.

    The following table describes the significant bits:

    Bit  Value   Description

    0    1       Do not format sensitive information.
         0       Format sensitive information.
    1    1       Build a column title for messages in brief format.
                 (You must specify a fmttyp of brief and a routin
                 argument.)
         0       Do not build column titles.