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.