VMS Help  —  SMB Routines, SMB$READ_MESSAGE_ITEM
    The SMB$READ_MESSAGE_ITEM routine reads a buffer that was filled
    in by the SMB$READ_MESSAGE routine, parses one message item from
    the buffer, writes the item's code into a longword, and writes
    the item into a buffer.

    Format

      SMB$READ_MESSAGE_ITEM  message ,context ,item_code ,buffer

                             [,size]

1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. Most utility routines return a
    condition value in R0. Condition values that this routine can
    return are listed under Condition Values Returned.

2  –  Arguments

 message

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Message items that SMB$READ_MESSAGE_ITEM is to read. The message
    argument is the address of a descriptor of a buffer. The buffer
    is the one that contains the message items that SMB$READ_MESSAGE_
    ITEM is to read. The buffer specified here must be the same as
    that specified with the call to the SMB$READ_MESSAGE routine,
    which fills the buffer with the contents of the message.

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Value initialized to 0 specifying the first message item in
    the buffer to be read. The context argument is the address of a
    longword that the SMB$READ_MESSAGE_ITEM routine uses to determine
    the next message item to be returned. When this value is 0,
    it indicates that SMB$READ_MESSAGE_ITEM is to return the first
    message item.

    The SMB$READ_MESSAGE_ITEM routine updates this value each time it
    reads a message item. SMB$READ_MESSAGE_ITEM sets the value to 0
    when it has returned all the message items in the buffer.

 item_code

    OpenVMS usage:smb_item
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Item code specified in the message item that identifies its type.
    The item_code argument is the address of a longword into which
    SMB$READ_MESSAGE_ITEM writes the code that identifies which item
    it is returning.

    The codes that identify message items are defined at the end of
    the Description help topic for this routine.

 buffer

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor
    Message item. The buffer argument is the address of a descriptor
    of a buffer. The buffer is the one in which the SMB$READ_MESSAGE_
    ITEM routine is to place the message item data. SMB$READ_MESSAGE_
    ITEM uses the Run-Time Library string-handling (STR$) routines to
    copy the message item data into the buffer.

 size

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference
    Size of the message item. The size argument is the address of a
    word in which the SMB$READ_MESSAGE_ITEM is to place the size, in
    bytes, of the item's data.

3  –  Description

    The job controller can request seven functions from the symbiont.
    They are identified by the following codes:

    SMBMSG$K_START_STREAM       SMBMSG$K_STOP_STREAM
    SMBMSG$K_START_TASK         SMBMSG$K_PAUSE_TASK
    SMBMSG$K_RESUME_TASK        SMBMSG$K_STOP_TASK
    SMBMSG$K_RESET_STREAM

    The job controller passes the symbiont a request containing
    a code and, optionally, a number of message items containing
    information the symbiont might need to perform the function. The
    code specifies what function the request is for, and the message
    items contain information that the symbiont needs to carry out
    the function.

    By calling SMB$READ_MESSAGE, the symbiont reads the request
    and writes the message items into the specified buffer. The
    symbiont then obtains the individual message items by calling
    the SMB$READ_MESSAGE_ITEM routine.

    Each message item consists of a code that identifies the
    information the item represents, and the item itself. For
    example, the SMB$K_JOB_NAME code tells the symbiont that the
    item specifies a job's name.

    The number of items in a request varies with each type of
    request. Therefore, you must call SMB$READ_MESSAGE_ITEM
    repeatedly for each request to ensure that all message items
    are read. Each time SMB$READ_MESSAGE_ITEM reads a message item,
    it updates the value in the longword specified by the context
    argument. SMB$READ_MESSAGE_ITEM returns the code SMB$_NOMOREITEMS
    after it has read the last message item.

    The following table shows the message items that can be delivered
    with each request:

    Request               Message Item

    SMBMSG$K_START_TASK   SMBMSG$K_ACCOUNT_NAME
                          SMBMSG$K_AFTER_TIME
                          SMBMSG$K_BOTTOM_MARGIN
                          SMBMSG$K_CHARACTERISTICS
                          SMBMSG$K_CHECKPOINT_DATA
                          SMBMSG$K_ENTRY_NUMBER
                          SMBMSG$K_FILE_COPIES
                          SMBMSG$K_FILE_COUNT
                          SMBMSG$K_FILE_IDENTIFICATION
                          SMBMSG$K_FILE_SETUP_MODULES
                          SMBMSG$K_FILE_SPECIFICATION
                          SMBMSG$K_FIRST_PAGE
                          SMBMSG$K_FORM_LENGTH
                          SMBMSG$K_FORM_NAME
                          SMBMSG$K_FORM_SETUP_MODULES
                          SMBMSG$K_FORM_WIDTH
                          SMBMSG$K_JOB_COPIES
                          SMBMSG$K_JOB_COUNT
                          SMBMSG$K_JOB_NAME
                          SMBMSG$K_JOB_RESET_MODULES
                          SMBMSG$K_LAST_PAGE
                          SMBMSG$K_LEFT_MARGIN
                          SMBMSG$K_MESSAGE_VECTOR
                          SMBMSG$K_NOTE
                          SMBMSG$K_PAGE_SETUP_MODULES
                          SMBMSG$K_PARAMETER_1

                              .
                              .
                              .
                          SMBMSG$K_PARAMETER_8
                          SMBMSG$K_PRINT_CONTROL
                          SMBMSG$K_SEPARATION_CONTROL
                          SMBMSG$K_REQUEST_CONTROL
                          SMBMSG$K_PRIORITY
                          SMBMSG$K_QUEUE
                          SMBMSG$K_RIGHT_MARGIN
                          SMBMSG$K_TIME_QUEUED
                          SMBMSG$K_TOP_MARGIN
                          SMBMSG$K_UIC
                          SMBMSG$K_USER_NAME
    SMBMSG$K_STOP_TASK    SMBMSG$K_STOP_CONDITION
    SMBMSG$K_PAUSE_TASK   None
    SMBMSG$K_RESUME_      SMBMSG$K_ALIGNMENT_PAGES
    TASK
                          SMBMSG$K_RELATIVE_PAGE
                          SMBMSG$K_REQUEST_CONTROL
                          SMBMSG$K_SEARCH_STRING
    SMBMSG$K_START_       SMBMSG$K_DEVICE_NAME
    STREAM
                          SMBMSG$K_EXECUTOR_QUEUE
                          SMBMSG$K_JOB_RESET_MODULES
                          SMBMSG$K_LIBRARY_SPECIFICATION
    SMBMSG$K_STOP_        None
    STREAM
    SMBMSG$K_RESET_       None
    STREAM

    The following list describes each item code. For each code, the
    list describes the contents of the message item identified by
    the code and whether the code identifies an item sent from the
    job controller to the symbiont or from the symbiont to the job
    controller.

    Many of the codes described are specifically oriented toward
    print symbionts. The symbiont you implement, which might not
    print files or serve an output device, need not recognize all
    these codes. In addition, it need not respond in the same way as
    the print symbiont to the codes it recognizes. The descriptions
    in the list describe how the standard print symbiont (PRTSMB.EXE)
    processes these items.

                                   NOTE

       Because new codes might be added in the future, you should
       write your symbiont so that it ignores codes it does not
       recognize.

4  –  Codes for Message Items

 SMBMSG$K_ACCOUNT_NAME

    This code identifies a string containing the name of the account
    to be charged for the job, that is, the account of the process
    that submitted the print job.

 SMBMSG$K_AFTER_TIME

    This code identifies a 64-bit, absolute-time value specifying the
    system time after which the job controller can process this job.

 SMBMSG$K_ALIGNMENT_PAGES

    This code identifies a longword specifying the number of
    alignment pages that the symbiont is to print.

 SMBMSG$K_BOTTOM_MARGIN

    This code identifies a longword containing the number of lines to
    be left blank at the bottom of a page.

    The symbiont inserts a form feed character into the output stream
    if it determines that all of the following conditions are true:

    o  The number of lines left at the bottom of the page is equal to
       the value in SMBMSG$K_BOTTOM_MARGIN.

    o  Sending more data to the printer to be output on this page
       would cause characters to be printed within this bottom margin
       of the page.

    o  The /FEED qualifier was specified with the PRINT command that
       caused the symbiont to perform this task.

    (Line feed, form feed, carriage-return, and vertical-tab
    characters in the output stream are collectively known as
    embedded carriage control.)

 SMBMSG$K_CHARACTERISTICS

    This code identifies a 16-byte structure specifying
    characteristics of the job. A detailed description of the format
    of this structure is contained in the description of the QUI$_
    CHARACTERISTICS code in the $GETQUI system service in the VSI
    OpenVMS System Services Reference Manual.

 SMBMSG$K_DEVICE_NAME

    This code identifies a string that is the name of the device to
    which the symbiont is to send data. The symbiont interprets this
    information. The name need not be the name of a physical device,
    and the symbiont can interpret this string as something other
    than the name of a device.

 SMBMSG$K_ENTRY_NUMBER

    This code identifies a longword containing the number that the
    job controller assigned to the job.

 SMBMSG$K_EXECUTOR_QUEUE

    This code identifies a string that is the name of the queue on
    which the symbiont stream is to be started.

 SMBMSG$K_FILE_COPIES

    This code identifies a longword containing the number of copies
    of the file that were requested.

 SMBMSG$K_FILE_COUNT

    This code identifies a longword that specifies, out of the number
    of copies requested for this job (SMBMSG$K_FILE_COPIES), the
    number of the copy of the file currently printing.

 SMBMSG$K_FILE_IDENTIFICATION

    This code identifies a 28-byte structure identifying the file
    to be processed. This structure consists of the following three
    file-identification fields in the OpenVMS RMS NAM block:

    1. The 16-byte NAM$T_DVI field

    2. The 6-byte NAM$W_FID field

    3. The 6-byte NAM$W_DID field

    These fields occur consecutively in the NAM block in the order
    listed.

 SMBMSG$K_FILE_SETUP_MODULES

    This code identifies a string specifying the names (separated by
    commas) of one or more text modules that the symbiont should copy
    from the library into the output stream before processing the
    file.

 SMBMSG$K_FILE_SPECIFICATION

    This code identifies a string specifying the name of the file
    that the symbiont is to process. This file name is formatted as a
    standard RMS file specification.

 SMBMSG$K_FIRST_PAGE

    This code identifies a longword containing the number of the page
    at which the symbiont should begin printing. The job controller
    sends this item to the symbiont. When not specified, the symbiont
    begins processing at page 1.

 SMBMSG$K_FORM_LENGTH

    This code identifies a longword value specifying the length (in
    lines) of the physical form (the paper).

 SMBMSG$K_FORM_NAME

    This code identifies a string specifying the name of the form.

 SMBMSG$K_FORM_SETUP_MODULES

    This code identifies a string consisting of the names (separated
    by commas) of one or more modules that the symbiont should copy
    from the device-control library before processing the file.

 SMBMSG$K_FORM_WIDTH

    This code identifies a longword specifying the width (in
    characters) of the print area on the physical form (the paper).

 SMBMSG$K_JOB_COPIES

    This code identifies a longword specifying the requested number
    of copies of the job.

 SMBMSG$K_JOB_COUNT

    This code identifies a longword specifying, out of the number of
    copies requested (SMBMSG$K_JOB_COPIES), the number of the copy of
    the job currently printing.

 SMBMSG$K_JOB_NAME

    This code identifies a string specifying the name of the job.

 SMBMSG$K_JOB_RESET_MODULES

    This code identifies a string specifying a list of one or more
    module names (separated by commas) that the symbiont should copy
    from the device-control library after processing the task. These
    modules can be used to reset programmable devices to a known
    state.

 SMBMSG$K_LAST_PAGE

    This code identifies a longword specifying the number of the
    last page that the symbiont is to print. When not specified, the
    symbiont attempts to print all the pages in the file.

 SMBMSG$K_LEFT_MARGIN

    This code identifies a longword specifying the number of spaces
    to be inserted at the beginning of each line.

 SMBMSG$K_LIBRARY_SPECIFICATION

    This code identifies a string specifying the name of the device-
    control library.

 SMBMSG$K_MESSAGE_VECTOR

    This code identifies a vector of longword condition codes, each
    of which contains information about the job to be printed.

    When LOGINOUT cannot open a log file for a batch job, a code in
    the message vector specifies the reason for the failure. The job
    controller does not send the SMBMSG$K_FILE_IDENTIFICATION item
    if it has detected such a failure but instead sends the message
    vector, which the symbiont prints, along with a message stating
    that there is no file to print.

 SMBMSG$K_NOTE

    This code identifies a user-supplied string that the symbiont is
    to print on the job flag page and on the file flag page.

 SMBMSG$K_PAGE_SETUP_MODULES

    This code identifies a string consisting of the names (separated
    by commas) of one or more modules that the symbiont should copy
    from the device-control library before printing each page.

 SMBMSG$K_PARAMETER_1 through SMBMSG$K_PARAMETER_8

    Each of these eight codes identifies a user-supplied string. Both
    the semantics and syntax of each string are determined by the
    user-defined symbiont. The OpenVMS-supplied symbiont makes no use
    of these eight items.

 SMBMSG$K_PRINT_CONTROL

    This code identifies a longword bit vector, each bit of which
    supplies information that the symbiont is to use in controlling
    the printing of the file.

    Symbol                    Description

    SMBMSG$V_DOUBLE_SPACE     The symbiont uses a double-spaced
                              format; it skips a line after each
                              line it prints.
    SMBMSG$V_NO_INITIAL_FF    The symbiont suppresses the initial
                              form feed if this bit is turned on.
    SMBMSG$V_NORECORD_        The symbiont performs single record
    BLOCKING                  output, issuing a single output record
                              for each input record.
    SMBMSG$V_PAGE_HEADER      The symbiont prints a page header at
                              the top of each page.
    SMBMSG$V_PAGINATE         The symbiont inserts a form feed
                              character when it detects an attempt
                              to print in the bottom margin of the
                              current form.
    SMBMSG$V_PASSALL          The symbiont prints the file without
                              formatting and bypasses all formatting
                              normally performed. Furthermore, the
                              symbiont outputs the file without
                              formatting, by causing the output QIO
                              to suppress formatting by the driver.
    SMBMSG$V_RECORD_BLOCKING  The symbiont performs record blocking,
                              buffering output to the device.
    SMBMSG$V_SEQUENCED        This bit is reserved by VSI.
    SMBMSG$V_SHEET_FEED       The symbiont pauses the queue after
                              each page it prints.
    SMBMSG$V_TRUNCATE         The symbiont truncates input lines that
                              exceed the right margin of the current
                              form.
    SMBMSG$V_WRAP             The symbiont wraps input lines that
                              exceed the right margin, printing the
                              additional characters on a new line.

 SMBMSG$K_PRIORITY

    This code identifies a longword specifying the priority this job
    has in the queue in which it is entered.

 SMBMSG$K_QUEUE

    This code identifies a string specifying the name of the queue
    in which this job is entered. When generic queues are used, this
    item specifies the name of the generic queue, and the SMBMSG$K_
    EXECUTOR item specifies the name of the device queue or the
    server queue.

 SMBMSG$K_RELATIVE_PAGE

    This code identifies a signed, longword value specifying the
    number of pages that the symbiont is to move forward (positive
    value) or backward (negative value) from the current position in
    the file.

 SMBMSG$K_REQUEST_CONTROL

    This code identifies a longword bit vector, each bit of which
    specifies information that the symbiont is to use in processing
    the request that the job controller is making.

    Symbol                    Description

    SMBMSG$V_ALIGNMENT_MASK   The symbiont is to replace all
                              alphabetic characters with the
                              letter X, and all numeric characters
                              with the number 9. Other characters
                              (punctuation, carriage control, and
                              so on) are left unchanged. This bit is
                              ordinarily specified in connection with
                              the SMBMSG$K_ALIGNMENT_PAGES item.
    SMBMSG$V_PAUSE_COMPLETE   The symbiont is to pause when it
                              completes the current request.
    SMBMSG$V_RESTARTING       Indicates that this job was previously
                              interrupted and requeued, and is now
                              restarting.
    SMBMSG$V_TOP_OF_FILE      The symbiont is to rewind the input
                              file before it resumes printing.

 SMBMSG$K_RIGHT_MARGIN

    This code identifies a longword specifying the number of
    character positions to be left empty at the end of each line.
    When the right margin is exceeded, the symbiont truncates the
    line, wraps the line, or continues processing, depending on the
    settings of the WRAP and TRUNCATE bits in the SMBMSG$K_PRINT_
    CONTROL item.

 SMBMSG$K_SEARCH_STRING

    This code identifies a string containing the value specified in
    the START/QUEUE/SEARCH command. This string identifies the page
    at which to restart the current printing task on a paused queue.

 SMBMSG$K_SEPARATION_CONTROL

    This code identifies a longword bit vector, each bit of which
    specifies an operation that the symbiont is to perform between
    jobs or between files within a job. The $SMBDEF macro defines the
    following symbols for each bit:

    Symbol                    Description

    SMBMSG$V_FILE_BURST       The symbiont is to print a file burst
                              page.
    SMBMSG$V_FILE_FLAG        The symbiont is to print a file flag
                              page.
    SMBMSG$V_FILE_TRAILER     The symbiont is to print a file trailer
                              page.
    SMBMSG$V_FILE_TRAILER_    The symbiont is to print a file trailer
    ABORT                     page when a task completes abnormally.
    SMBMSG$V_FIRST_FILE_OF_   The current file is the first file of
    JOB                       the job. When specified with SMBMSG$V_
                              LAST_FILE_OF_JOB, the current job
                              contains a single file.
    SMBMSG$V_JOB_FLAG         The symbiont is to print a job flag
                              page.
    SMBMSG$V_JOB_BURST        The symbiont is to print a job burst
                              page.
    SMBMSG$V_JOB_RESET        The symbiont is to execute a job reset
                              sequence when the task completes.
    SMBMSG$V_JOB_RESET_ABORT  The symbiont is to execute a job
                              reset sequence when a task completes
                              abnormally.
    SMBMSG$V_JOB_TRAILER      The symbiont is to print a job trailer
                              page.
    SMBMSG$V_JOB_TRAILER_     The symbiont is to print a job trailer
    ABORT                     page when a task completes abnormally.
    SMBMSG$V_LAST_FILE_OF_    The current file is the last file of
    JOB                       the job. When specified with SMBMSG$V_
                              FIRST_FILE_OF_JOB, the current job
                              contains a single job.

 SMBMSG$K_STOP_CONDITION

    This code identifies a longword containing a condition specifying
    the reason the job controller issued a STOP_TASK request.

 SMBMSG$K_TIME_QUEUED

    This code identifies a quadword specifying the time the file was
    entered into the queue. The time is expressed as 64-bit, absolute
    time.

 SMBMSG$K_TOP_MARGIN

    This code identifies a longword specifying the number of lines
    that the symbiont is to leave blank at the top of each page.
    PRTSMB inserts line feeds into the output stream after every form
    feed until the margin is cleared.

 SMBMSG$K_UIC

    This code identifies a longword specifying the user
    identification code (UIC) of the user who submitted the job.

 SMBMSG$K_USER_NAME

    This code identifies a string specifying the name of the user who
    submitted the job.

5  –  Condition Values Returned

    SS$_NORMAL         Normal successful completion.
    SMB$_NOMOREITEMS   End of item list reached.

    This routine also returns any condition code returned by the
    Run-Time Library string-handling (STR$) routines.
Close Help