 |
OpenVMS Utility Routines Manual
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]
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.
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 section 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.
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_TASK
|
SMBMSG$K_ALIGNMENT_PAGES
|
|
|
SMBMSG$K_RELATIVE_PAGE
|
|
|
SMBMSG$K_REQUEST_CONTROL
|
|
|
SMBMSG$K_SEARCH_STRING
|
|
SMBMSG$K_START_STREAM
|
SMBMSG$K_DEVICE_NAME
|
|
|
SMBMSG$K_EXECUTOR_QUEUE
|
|
|
SMBMSG$K_JOB_RESET_MODULES
|
|
|
SMBMSG$K_LIBRARY_SPECIFICATION
|
|
SMBMSG$K_STOP_STREAM
|
None
|
|
SMBMSG$K_RESET_STREAM
|
None
|
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.
|
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:
- The number of lines left at the bottom of the page is equal to the
value in SMBMSG$K_BOTTOM_MARGIN.
- 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.
- 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 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:
- The 16-byte NAM$T_DVI field
- The 6-byte NAM$W_FID field
- 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_BLOCKING
|
The symbiont performs single record 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 Compaq.
|
|
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_ABORT
|
The symbiont is to print a file trailer page when a task completes
abnormally.
|
|
SMBMSG$V_FIRST_FILE_OF_JOB
|
The current file is the first file of 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_ABORT
|
The symbiont is to print a job trailer page when a task completes
abnormally.
|
|
SMBMSG$V_LAST_FILE_OF_JOB
|
The current file is the last file of 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.
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.
|
