OpenVMS Utility Routines Manual

Document revision date: 19 July 1999

OpenVMS Utility Routines Manual

Contents

Index

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.

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

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.

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.

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.

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.

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.

Contents

Index

privacy and legal statement

4493PRO_048.HTML

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

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

OpenVMS usage:	context
type:	longword (unsigned)
access:	modify
mechanism:	by reference

OpenVMS usage:	smb_item
type:	longword (unsigned)
access:	write only
mechanism:	by reference

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

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