Specification for a Generic Interface to the SAP
NetWeaver Spool System for External Output
Management Systems
(BC-XOM)
Integration and Certification Center
[email protected]
Interface Version: 2.0
Document Version 4.40
June 25, 2014
BC-XOM INTERFACE DOCUMENT
Document Details
Name
BC-XOM
Interface Document
Objective
SAP Interface
Integration
Audience
SAP Partners
For any info on this document please contact:
Name
SAP Integration and Certification Center
Description
Specification for a Generic Interface to
the SAP NetWeaver Spool System for
External Output Management Systems
(BC-XOM)
Email ID
[email protected]
Change Log
Version
Date
3.40
Jan 07, 1999
4.00
Mar 09, 2001
4.20
May 05, 2002
4.323
June 05, 2002
4.40
June 16, 2014
Author
Uwe Krüger
Uwe Krüger
Uwe Krüger
Martin Vierling
Martin Vierling
Description
Initial document
Documentation Extension / Correction
Documentation Extension / Correction
Documentation Extension / Correction
Use of BAPIS for XMI
Document Release
Version
Date
4.40
June 16, 2014
Approved By
Martin Vierling
Description
Use of BAPIS for XMI
SAP Integration and Certification Center
2
BC-XOM INTERFACE DOCUMENT
TABLE OF CONTENTS
1.
1.1
1.1.1
1.1.2
1.1.3
1.1.3.1
INTRODUCTION ................................................................................................................................. 5
Current Implementation of the R/3 Spool System ......................................................................... 5
Storage System ................................................................................................................................... 5
Actual Spool System ........................................................................................................................... 5
Device Descriptions............................................................................................................................. 5
Devices ............................................................................................................................................ 6
1.1.3.2
Device Types ................................................................................................................................... 7
1.1.4
Formatting System .............................................................................................................................. 7
1.1.5
Output System..................................................................................................................................... 8
1.1.5.1
Access Methods .............................................................................................................................. 8
1.1.6
1.2
1.3
1.3.1
1.3.1.1
Spool Work Process ............................................................................................................................ 9
Problems with the Current Solution ................................................................................................ 9
Approaches to a Solution ................................................................................................................. 9
Short-Term Possibilities ...................................................................................................................... 9
Reduction of the variety of possible errors and delays in connection with access methods........... 9
1.3.1.2
Enhanced Feedback Possibilities .................................................................................................... 9
1.3.2
Longer-Term Goals ........................................................................................................................... 10
1.3.2.1
Complete RFC Interface ................................................................................................................ 10
1.3.2.2
Integration of Device Management ............................................................................................... 11
1.3.2.3
Transfer of Print Formatting ........................................................................................................... 11
1.4
CCMS Interface for External Management Tools (XMI) ............................................................... 11
1.4.1
Interface Embedding ......................................................................................................................... 11
1.4.1.1
Logon to an SMAPI ....................................................................................................................... 11
1.4.1.2
Logoff from a SMAPI ..................................................................................................................... 12
1.4.1.3
Writing Log Information from the External Tool ............................................................................. 13
1.4.2
Messages .......................................................................................................................................... 13
1.4.2.1
Language Independent Messages ................................................................................................ 13
1.4.2.2
Language-Dependent Messages .................................................................................................. 14
1.4.2.3
Time Zone Independent Messages ............................................................................................... 14
2.
2.1
2.2
2.2.1
2.2.2
2.3
2.4
2.5
2.5.1
2.5.1.1
REAL AND LOGICAL OMS ............................................................................................................. 14
Background ..................................................................................................................................... 14
SAP Tables....................................................................................................................................... 15
LOMS Definition ................................................................................................................................ 15
ROMS ................................................................................................................................................ 16
Interface Design .............................................................................................................................. 16
Reply Message Groups (RMG)....................................................................................................... 17
Command Line Interface ................................................................................................................ 18
General Requirements ...................................................................................................................... 18
Arguments ..................................................................................................................................... 18
2.5.1.2
Results ........................................................................................................................................... 19
2.5.1.3
Messages ...................................................................................................................................... 19
2.5.1.4
Response time ............................................................................................................................... 19
2.5.2
Job Submission ................................................................................................................................. 19
SAP Integration and Certification Center
3
BC-XOM INTERFACE DOCUMENT
2.5.3
2.5.4
2.5.5
2.5.6
2.6
2.6.1
2.6.1.1
Device-Polling ................................................................................................................................... 21
Device Query Command (User-Controlled) ...................................................................................... 22
Job Cancellation ................................................................................................................................ 24
Job query........................................................................................................................................... 24
Callback Interface............................................................................................................................ 24
General design .................................................................................................................................. 25
Configuration of the OMS client..................................................................................................... 25
2.6.2
Configuration Interface ...................................................................................................................... 26
2.6.2.1
RMG configuration ......................................................................................................................... 27
2.6.2.2
Device configuration ...................................................................................................................... 27
2.6.2.3
Reconfiguration ............................................................................................................................. 28
2.6.3
Callbacks ........................................................................................................................................... 28
2.6.3.1
Report Levels................................................................................................................................. 28
2.6.3.2
Event Messages ............................................................................................................................ 29
2.6.3.3
General Exceptions for RFC Calls ................................................................................................ 29
2.6.3.4
Job Callback .................................................................................................................................. 29
2.6.3.5
Device callback .............................................................................................................................. 30
2.6.3.6
Logging Event Messages in XMI ................................................................................................... 30
2.7
2.7.1
2.7.2
2.8
2.8.1
2.8.1.1
Callback Target (SAP Instance) Does Not Respond to RFC Callback ....................................... 30
At least one alternative target is still up ............................................................................................ 31
All targets are down .......................................................................................................................... 31
RFC Server Interface ....................................................................................................................... 31
General design .................................................................................................................................. 31
Configuration of the OMS Server .................................................................................................. 32
2.8.2
Job Submission ................................................................................................................................. 33
2.8.2.1
Starting a job submission .............................................................................................................. 33
2.8.2.2
Finish a job submission ................................................................................................................. 35
2.8.3
2.8.4
2.8.5
2.8.6
Device Polling.................................................................................................................................... 35
Device Query..................................................................................................................................... 36
Job Cancellation ................................................................................................................................ 37
Job Query .......................................................................................................................................... 38
3.
3.1
3.2
APPENDIX ........................................................................................................................................ 39
Appendix A - Codes ........................................................................................................................ 39
Appendix B - Examples .................................................................................................................. 41
SAP Integration and Certification Center
4
BC-XOM INTERFACE DOCUMENT
1. INTRODUCTION
SAP has developed an open generic interface to the R/3 spool system for external output management
systems (OMS). This document describes this interface, which is part of the CCMS (Computing Center
Management System) interface package for the integration of external software components. The interface
is based upon the POSIX 1387-Standard, but can in principle be used by all OMSs which support the
required functionality. The interface is not based upon the specific command set defined by the POSIX
standard.
1.1 Current Implementation of the R/3 Spool System
The current R/3 spool system is organized into five functional areas:
1. Storage system
2. Actual spool system
3. Device descriptions
4. Formatting system
5. Output system
Functional areas 4 and 5 are implemented in a special SAP work process, the Spool Work Process (SWP).
1.1.1 Storage System
The storage system (TemSe) provides a physical repository for documents which are produced by programs
in the R/3 System. Data can be stored either in the R/3 database or in the file system of the host operating
system. Data is stored in partially-formatted form (OTF formatting) using a descriptive format. Before
output, such data is formatted according to the requirements of the specific output device type by the
formatting system.
1.1.2 Actual Spool System
A user initially generates a document (called spool request) , which is held in the storage system. To start
the output, one or more output requests have to be created for the document. These two steps can be
combined with the “Immediate Print” option when printing. With the “Delete” option, a document and all of its
output requests are deleted after being printed. It’s also possible to delete upon user request or using a
program and expiration date.
1.1.3 Device Descriptions
When a user wishes to generate output requests from the R/3 System, the user needs a name for the target
output device. The output system also needs information about the physical device to which this name
belongs and how this device can be addressed. For these reasons, there must be a representation of an
output device within the R/3 System (see 1.1.3.1).
In addition to its actual task of outputting data from within the R/3 System to external devices or software
components, the R/3 spool system also supports device-specific formatting of data that is to be output,
starting from a generic internal formatting. This formatting converts the R/3 data stream into a format/printer
language which the target device understands. The information required for this formatting is not usually
associated with a particular printer, but is rather shared by all printers of a particular type. Accordingly, the
description of the properties of a set of devices for the formatting system is held in a separate representation
which can be shared by many devices. This representation is called a device type (see 1.1.3.2).
SAP Integration and Certification Center
5
BC-XOM INTERFACE DOCUMENT
Storage Management
Spooling
Device Management
Spool Request
Attributes
Raw Print
Data
Device
Attributes/
Description
Print Request 1
<n>
Spool Work Process
Application Server
and Database
DeviceType
Description
Code Page
Print Controls
Output Sequences
for Printable
Characters
(Bold/Italic/)
...
Formats +
Actions
Device Init
Start of Page
Start of Line
Codepage
Conversion
Formatting
Insertion of: Print Controls
Printer Actions
Data Transfer/
Connection Management
Status
Querying
R/3
OS/
Network
Printer
Figure 1: SAP R/3 Spooling Architecture Overview
1.1.3.1 Devices
Output devices in R/3 identify output targets and are represented as independent objects in R/3. At the
same time, these objects refer to information about the properties of the device. Most importantly, the device
identifies the device type, which contains the information required for the formatting of output for the device
(see 1.1.3.2). In addition, an R/3 device also contains information required for the identification and
accessing of physically extant devices or software components. This information includes the name of the
device in the external software component that drives the device, as well as information that specifies these
components and indicates how the connection from the R/3 System to these components is to be
established. The type of connection is specified in the access method, which also determines the
information that is required for establishing the connection. (see 1.1.5.1).
SAP Integration and Certification Center
6
BC-XOM INTERFACE DOCUMENT
1.1.3.2 Device Types
A device type describes formatting characteristics that are common to a class of identical devices. This
includes the following information:
 Character set
 Formats
 Print controls
 OTF formatting information
- Information on the printer fonts and font metrics
- The OTF printer driver
1.1.3.2.1 Character Set / Code Page
This specification is used during formatting to convert data from the system character set to a character set
that the printer understands. A character set defines the strings that cause a printer, in conjunction with the
formatting to print the corresponding characters.
1.1.3.2.2 Formats
Printers can usually output in various font sizes and in portrait or landscape mode. Correspondingly, it’s
possible to define a set of formats for a device, such as X_65_80 for list output with 65 lines and 80 columns.
Each format consists of actions, which contain data that is transmitted to the printer when certain conditions
or events occur. Action data is transmitted by being embedded in the output stream at the appropriate
points. Actions include for example the following:
 printer initialization
 page start
 page end
 line start
 line end
 and many others
1.1.3.2.3 Print Controls
Print controls describe changes in the attributes of an output stream, such as the following:
 font or typeface
 font size
 boldface or italic
For each device type, a print control can be defined with the string that instructs printers of that type to carry
out the required function. Print controls are embedded by name in the output data by applications that
generate the output using ABAP language constructs. The formatting process replaces the print controls in
the output stream with the printer-specific string.
1.1.4 Formatting System
The formatting system uses the information in the device type to prepare raw data from the R/3 System for
output on a printer. The formatting system generates a data stream that can be understood by the printer
(for example, PostScript or PCL). In addition to replacing print controls and embedding the actions of the
selected format, the formatting system also converts the SAP internal characters to the printer character set
or to the strings that cause the printer to output the corresponding characters (e.g. calls of macros which
have been defined in the printer setup).
SAP Integration and Certification Center
7
BC-XOM INTERFACE DOCUMENT
The formatting system distinguishes between several types of output data streams:
 list output
Uses a table-driven driver consisting of the formats and actions described above (1.1.3.2.2)
 OTF output
Uses special OTF drivers for various printer languages in addition to the actions.
 direct output
Output data is delivered by the printing application already formatted for the correct device type. This
print data can be sent directly to the output device by the output system without any further processing.
1.1.5 Output System
In addition to specifying the attributes of a device type, which depend only upon the printer, a device
definition also contains additional configuration information that tells the R/3 System how the device can be
accessed or addressed. R/3 offers various methods for establishing this connection. These are known as
access methods. Each method possesses a series of attributes, which contain the information on how to
access a device from the output system using the corresponding method. Generally, the existence of a
spool system in the host operating system to which the R/3 output request can be passed is a prerequisite.
Network printers are an exception to this rule since under certain conditions they can be directly addressed
using an access method. This is because they emulate (even though to a limited extent) the functionality of a
spool system.
The formatting and output systems are bundled in a special work process type, the spool work process. The
output system in the spool work process is divided into two functional areas:
1. Transmission of output requests.
2. For each output request, a separate connection to the target output device is established according to the
access method. The formatted data of the output request is then transferred.
3. Querying of output requests by device
4. After successful transmission, the print queue of the output device is regularly checked for SAP print jobs.
Jobs that are no longer present in the queue are designated as completed in the SAP spool system.
1.1.5.1 Access Methods
The realization of the transmission and querying of a request is determined by the type of communication
connection, the access method. The current R/3 Release offers the following access methods:
Access
method
L, N
C
U
S
Z
Function
Local print relative to the spool work process. This access method uses a
command line interface to the local host spooler, such as the command sets
lpr/lpq or lp/lpstat. The output data is written by the output system to a file,
which is then passed to the print command as an argument. The syntax of
the command is specified in the SAP system profile and can therefore be
instance specific.
Local print relative to the spool work process. In this access method, the
local host spooler is addressed directly by way of the programming
interface. In this method as well, a file is generated and then transferred.
This access method has in the past been supported only for Windows NT
and AS400.
TCP/IP connection to an RFC1179-compatible host spooler. With certain
restrictions, this access method can be used to address network printers
directly, without an intermediary host spool system.
TCP/IP connection to an SAPLPD on a Windows system.
Custom Printing. Spool exit for AFP printing.
SAP Integration and Certification Center
8
BC-XOM INTERFACE DOCUMENT
1.1.6 Spool Work Process
The spool work process is a work process in an SAP R/3 instance whose sole function is the formatting and
output of output requests. To this purpose, each output device in an R/3 spool system is assigned to exactly
one R/3 instance with a spool work process, which is then responsible for the correct performance of output
requests for this device. These processes can, however, be responsible for an unlimited number of R/3
output devices.
A spool work process can process only a single output request or device query at a time.
1.2 Problems with the Current Solution
The problems of the current solution can be roughly divided into four groups:
1. Incorrect configuration of device types
2. Deficient feedback as to the status of output requests and devices
Error information which pertains to the host spool printing process is not displayed and is not available
within the R/3 System.
3. Problems with status querying
Polling burdens the SWP unnecessarily, which can lead to delayed processing of output. Without
querying, there is no way to determine whether a request has been completed or not. The differing
formats of feedback messages makes parsing the output of polling commands difficult and often results in
problems or errors in the (already limited) feedback.
4. Problems with the connections to printers
Through the various access methods -- and in particular through the network access methods -- a variety
of error situations can occur, which can in turn produce unacceptable processing delays in an SWP, for
example when a remote computer or printer is not reachable. In addition, the potentially very complicated
path from the SWP to the printer precludes the availability of analysis methods for identifying the source
of a problem.
1.3 Approaches to a Solution
The general approach to a solution is a reduction of the complexity of the R/3 spool system by transferring
functions to an external output management system (OMS). Given the path that output requests take
through the R/3 System, various levels of function transfer are thinkable, characterized by significantly
differing degrees of integration. As the degree of integration increases, so does the capability of delegating
more and complex tasks to the external system, as does the level of the solution. Correspondingly, it is
possible to distinguish between short-term and longer-term problem solving strategies.
1.3.1 Short-Term Possibilities
1.3.1.1 Reduction of the variety of possible errors and delays in connection with access methods.
The goal is here a purely local transmission of data to a spool system which is running on the same host
system as the SWP. Since the transmission takes places locally, at least initially the very simple command
interface already available with access method L can be used.
1.3.1.2 Enhanced Feedback Possibilities
By way of an RFC callback interface, current status information on R/3 jobs and devices can be passed
asynchronously from the OMS to the R/3 System without resort to costly polling. At the same time, better
information can be delivered by way of this interface than by way of standard LPQ commands. An RFC
client is adequate for active feed back. Server functionality on the part of the OMS is not required.
SAP Integration and Certification Center
9
BC-XOM INTERFACE DOCUMENT
As a first step, an extended command line interface with an expanded information format could be used
instead of an active callback mechanism in the OMS. Upon status request by a user, this extended
command line interface could be activated.
RFC
System : C11
Dispatcher
Dialog
g
Spool
Query Status
Submit Command
Output
Management
System
Callback Spool Event
Printer
Output
Outpu
t
Figure 2: Interface to Output Management System
1.3.2 Longer-Term Goals
The short-term goals allow a simple functional solution without requiring a deeper integration. The longerterm goals foresee, by contrast, such a integration.
1.3.2.1 Complete RFC Interface
The first step in the direction of a deeper integration is the replacement of the command line interface with a
complete (realized on both sides) RFC interface. The client in the OMS thereby takes on in addition a server
role, from the viewpoint of the R/3 System.
The level of intersection between R/3 and the OMS remains the same. Only the coupling of the systems
becomes tighter and therefore more homogenous. Jobs can now be started directly from the R/3 System.
Additionally, attributes can be queried and jobs can be manipulated. This functionality is available by way of
function modules right at the level of ABAP/4 programming, the function modules being realized by the OMS.
An overview of the status of an external system is also directly accessible in the R/3 System by means of the
logon of the external system to the R/3 System. This means that no direct access to the operating system is
required in order to perform maintenance work.
SAP Integration and Certification Center
10
BC-XOM INTERFACE DOCUMENT
1.3.2.2 Integration of Device Management
A possible extension to this first step would be a standardization of the device models among the various
systems. This would allow an integration of the device administration, so that devices would not have to be
configured redundantly at the host system and R/3 levels.
1.3.2.3 Transfer of Print Formatting
In a further step, the configuration information that is required in the R/3 System (in the form of device types)
could be drastically reduced by transferring the formatting of print data for certain types of printers to the
external system.
With R/3 release 3.1G a device independent output format SAPGOF (SAP Generic Output Format) is
available. It allows external formatting tools to get all information for a document to be formatted that is
available inside the R/3 spool system (including a unique representation for all characters used in R/3). This
format can be passed to an external system by all access methods.
1.4 CCMS Interface for External Management Tools (XMI)
The XMI interface is a general framework for the CCMS (Computing Center Management System) external
system management interfaces. As a framework, the XMI functionality can only be usefully employed in
conjunction with other interfaces providing additional functionality for a particular application area. On the
other hand this additional functionality can only be used in conjunction with the XMI interface. The interfaces
for particular application areas are called SMAPIs (System Management Application Programming Interface).
Each SMAPI is named and can be explicitly requested by establishing an XMI connection.
The SMAPI used for the OMS interface is called ‘XOM’ (eXternal Output Management) .The version
string of the interface described in this document is ‘0.1’.
A second task of the XMI framework is to provide an interface for language-independent messages. This
interface will be generally used for logging external messages inside R/3. In addition XOM uses this interface
to provide language-independent event texts for job and device callbacks for end users of the R/3 spooling
system.
This chapter highlights only some features and functions of the XMI interface that are important for the
SMAPI ‘XOM’ described in this document. More information can be found in the document ‘Connecting
External System Management Tools to the R/3 CCMS -- Interface Framework’.
1.4.1 Interface Embedding
In order to control access from external programs to R/3 functions, the XMI framework uses additional
functions for connecting to specific SMAPIs. It is used as an extension to the R/3 RFC connection
mechanism. The framework also provides interface functions for querying information about SMAPIs and
supported versions.
To connect to a specific SMAPI (e.g. XOM), the external program must establish an RFC connection to an
R/3 application server. Using this connection it is possible to use the XMI framework functions to connect to
and to disconnect from specific SMAPIs. To do so the XMI functions BAPI_XMI_LOGON and
BAPI_XMI_LOGOFF must be called. Only after a successful connection to an SMAPI with
BAPI_XMI_LOGON it is possible to call interface functions of the corresponding SMAPI.
1.4.1.1 Logon to an SMAPI
The logon procedure establishes a user context in R/3 for the current RFC connection. This context contains
some important information like the requested version for each connected SMAPI. Therefore the SMAPI
functions don’t need extra parameters for this information. It also checks whether the external tool is allowed
to use the desired SMAPI and whether the desired version of the SMAPI is supported by the current R/3
SAP Integration and Certification Center
11
BC-XOM INTERFACE DOCUMENT
system. The parameters and the result of this check will be used for further calls of SMAPI functions. It is
possible to build connections to more than one SMAPI within the same RFC connection to an R/3 system.
The BAPI_XMI_LOGON call requires the following arguments:
Field
EXTCOMPANY
EXTPRODUCT
INTERFACE
(optional)
VERSION
(optional)
Data type
Char(16)
Char(16)
Char(3)
Meaning
Manufacturer of the external program
Product name of the external program
SMAPI name (e.g. XOM)
Char(10)
SMAPI version expected by the external program
The RFC delivers the following results:
Field
Data type
SESSIONID
Char(24)
Meaning
Unique identification of an XMI session
The following exceptions may occur:
Exception
Meaning
LOGON_DENIED
The logon was refused because the R/3 user used by the
external management system is not authorized to work with the
external management tool for the desired SMAPI.
INVALID_PARAMETERS
EXTCOMPANY and EXTPRODUCT are different within the same
session. These arguments should have the same values for each
call for an XMI session.
UNKNOWN_INTERFACE
The interface requested by the external tool is not supported.
ALREADY_LOGGED_ON The requested interface is already logged on.
UNKNOWN_VERSION
The version required by the external tool is not supported.
CANT_LOG_ACTION
The action was terminated because the R/3 XMI logging
mechanism returned an error.
PROBLEM_DETECTED
A problem not directly related to XMI functionality has occurred in
an XMI function module. This is probably caused by another
function module which has been called. Consult the syslog.
1.4.1.2 Logoff from a SMAPI
In the event of a successful logon, the external tool should logoff from the connected SMAPIs after all work
has been done.
The BAPI_XMI_LOGOFF call accepts the following arguments:
Field
INTERFACE
(optional)
Data type
Char(3)
Meaning
SMAPI name (e.g. XOM)
The following exceptions may occur:
Exception
Meaning
NOT_LOGGED_ON
There is no logon to the SMAPI.
CANT_LOG_ACTION
The action was terminated because the R/3 XMI logging
mechanism returned an error.
PROBLEM_DETECTED
A problem not directly related to XMI functionality has occurred in
an XMI function module. This is probably caused by another
function module which has been called. Consult the syslog.
SAP Integration and Certification Center
12
BC-XOM INTERFACE DOCUMENT
1.4.1.3 Writing Log Information from the External Tool
If the external tool wants to write log information that should be accessible in R/3 it can do so by using the
XMI_LOGMSG_ENTER call. See the XMI document for further details.
1.4.2 Messages
The XMI framework contains formats and mechanisms for supporting language independent messages.
These messages will be translated into the logon language of the user who displays the messages. This
mechanism also allows messages containing only plain text if an external tool cannot deliver translatable
messages.
To achieve this, each message is split into a message identifier, arguments and a message text. The
identifier specifies a message with a specific meaning. It consists of two components: a company identifier
(which must be obtained from SAP AG) and a message id. The company identifier describes a separate
company-specific name space. The message ids are only valid inside this name space and can be chosen
freely by the company managing the name space.
The arguments are delivered as typed strings. The types include string, integer, float, date and time. The
arguments are displayed using the user parameter configuration of the displaying users (e.g. time zone, date
and floating point formats).
Messages for XMI or SMAPI interface functions have the following components:
Field
MSGCLASS
MSGID
MSGARG1
ARGTYPE1
MSGARG2
ARGTYPE2
MSGARG3
ARGTYPE3
MSGARG4
ARGTYPE4
MSGTEXT
Meaning
Company name range
Company name range private message id
Argument string for the first argument
Argument type for the first argument
Argument string for the second argument
Argument type for the second argument
Argument string for the third argument
Argument type for the third argument
Argument string for the fourth argument
Argument type for the fourth argument
Default translation of the message
1.4.2.1 Language Independent Messages
It is possible to define language-dependent message templates for each supported language for such an
identifier. These templates may contain replacement characters to mark places for parameters in which the
current arguments of the concrete message should be filled in.
The templates are stored in the R/3 database, while the arguments are delivered again with every message.
When a message is displayed, the message identifier will be used together with the current language to look
up a message template for the message. Together with the current arguments a translated message will be
produced by scanning the template for replacement characters and inserting the arguments.
In addition to these required components of a language independent message, the XMI message format
requires a further field containing a message text/template, a default translation of the message. This default
template will be used to translate the message if the R/3 database contains no translation entry for the
current message identifier. As with language-dependent templates, this message may contain replacement
strings for parameters.
To use language-independent messages the external tool must upload the language-dependent message
templates into the R/3 database. This must be done only once before using the messages. A good time for
this upload is the installation process of the tool. The XMI framework provides a special function module for
this upload process (BAPI_XMI_UPLOAD_MSG_FORMATS).
SAP Integration and Certification Center
13
BC-XOM INTERFACE DOCUMENT
The BAPI_XMI_UPLOAD_MSG_FORMATS call accepts the following arguments:
Field
FORMATS
Data type
BAPIXMMSG
Meaning
Language-dependent formats of external messages
The following exceptions may occur:
Exception
Meaning
NOT_LOGGED_ON
Tool not logged on in XMI framework
INVALID_PARAMETERS
Arguments have invalid values
CANT_UPLOAD
PROBLEM_DETECTED
Internal problem (see system log)
CANT_LOG_ACTION
Action could not be logged
If a company provides more than one tool, it needs only one company name space. How the message ids
are distributed among the different tools may be managed by the company. But once a message id has a
defined meaning, this id may not be used for another meaning, because there still may be old messages
stored inside R/3 with the old meaning which still need to be displayed correctly.
1.4.2.2 Language-Dependent Messages
As an alternative to language-independent messages, it is still possible to use language-dependent
messages, if the external tool cannot handle language-independent ones.
If no identifier is specified for the message (identifier field left blank), then the default message text will
always be used. This allows plain text messages. In this case the default message MUST be fully translated
with inserted arguments. The message text will not be used as a template for parameter substitution!
1.4.2.3 Time Zone Independent Messages
All time stamps should be delivered in UTC (Universal Time Coordinated). They will be converted to the local
time of the users who display the time stamps. If a time stamp is part of a message, a special argument type
for UTC time stamps should be used. The SAP UTC time stamp has the format: YYYYMMDDHHMMSS, for
example, 12/18/1996 CET 14:06:35 would be 19961218130635.
2. REAL AND LOGICAL OMS
2.1 Background
The interface from R/3 to external OMSs must permit support for multiple OMSs. This is required to allow
use of different OMSs by different R/3 Systems as well as to support multiple OMSs from a single R/3
System. At the same time, it is sensible to operate an OMS in multiple modes with respect to different
devices. For example, it may be appropriate to operate important printers in a callback mode, insofar as this
is supported by the OMS, so as to receive timely and accurate information. Simultaneously, other devices
may be operated in polling mode using a long time interval to minimize the computing power required. By
the same token, it may be useful to display information in the alert monitor on the device status of certain
printers independently of requests, while refraining from this for other less important devices.
That is, multiple OMS systems must be configurable in multiple modes within an R/3 System. This suggests
the need for the concept of the logical OMS (LOMS).
SAP Integration and Certification Center
14
BC-XOM INTERFACE DOCUMENT
2.2 SAP Tables
2.2.1 LOMS Definition
The LOMS bundles the operating mode, other configuration parameters, and the underlying real OMS
(ROMS).
Within the R/3 System, LOMSs are represented in the following table (* indicates key field):
TSPLOMS (Customer naming space)
*NAME
RNAME
DESCR
CMDSERVER
Char(6)
Char(10)
Char(60)
Char(40)
CALLBTRGT
JCALLBIV
JCALLBAMNT
DCALLBIV
DCALLBAMNT
RETRYIV
R3FLAGS
Char(40)
numc(3)
numc(3)
numc(3)
numc(3)
numc(3)
Char(60)
Char 1..2
Char 3
Char 4
Char 5
Char 6
Char 7
Char 8
OMSFLAGS
UPDATEFLG (int.
use)
1
Char 9
Char 10
Char
11..60
Char(60)
Char(1)
Name of the logical OMS
Real OMS (e.g. PSM, DAZEL, Xprint, ...)
Textual description of the OMS
SAP instance issuing commands (i.e. job query, cancel,
global device query)
Target SAP instance for callback
Job callback time interval in seconds
max. buffering (number of events) for jobs
Device callback time interval in seconds
max. buffering (number of events) for devices
Time for retry of callback in seconds (see 2.7)
Configuration options for an LOMS
Currently, the following are defined:
Callback Report Class (Table 2)
Job Query allowed
Use Job Callback (step 2) otherwise polling (step 1)
Use Device Callback (step 2)
1
Fax (not used see also 2.2.2)
Set job to error state, if device polling does not
return information for job.
Command group for operating system commands
(internal use for configuration transaction)
Job Cancel allowed
Device Query allowed
Reserved for future use
LOMS configuration by OMS.
X = update required,’ ‘= valid
Using Fax is not supported for Access Method E, see SAP Note 502604
SAP Integration and Certification Center
15
BC-XOM INTERFACE DOCUMENT
2.2.2 ROMS
Each LOMS refers to exactly one real OMS (ROMS). ROMS also have a representation in the R/3 System:
TSPROMS
*NAME
DESCR
STARTINST
STARTCMD
RECONFIG
Char(10)
Char(60)
Char(40)
Char(132)
Numc(3)
R3FLAGS
Char(60)
Char 1
Char 2
Char 3
Char 4
Char 5
Char 6
Char 7
Char 8
Char 9
Char
10..60
Char(60)
Char(1)
OMSFLAGS
UPDATEFLG (int. use)
Real OMS (e.g. PSM)
Textual description of the OMS
SAP instance that is to start client
Start command for ROMS client (see 2.6.1.1)
Time interval for reconfiguration in seconds (see
2.6.2.3)
R/3 configuration options for ROMS
 Job query supported
 Job callback supported
 Device callback supported
 Fax (not used see also 2.2.1)
 Polling supported
 Cancel supported
 Device Query supported
 RFC Server interface
 Command Line interface
Reserved for future use
ROMS configuration by OMS.
X = update required,’ ‘= valid
2.3 Interface Design
A new access method E will be defined in R/3. The interface will be based in part on the existing command
line interface for job transfer and device querying. The polling procedure from access method L will be reused but will use an expanded output format for the status query. This expanded format will be defined in
R/3 and not by the OMS.
Further, a method for obtaining more detailed job information upon user request will be provided. This will
deliver additional information that is not meaningful for the R/3 system and which therefore is not relevant to
the polling procedure.
As an alternative to the polling procedure, the OMS will have the option of using a callback interface. The
activity of transmitting an event will be initiated by the OMS so that cyclical querying no longer is required. In
combination, these options allow the following modes, which can be selected in the LOMS.
Mode
A
Job
Callback
-
Device
Callback
-
Job
Query
-
B
-
-
X
C
X
-
-
D
E
X
-
X
X
-
F
G
H
X
X
X
X
X
X
X
SAP Integration and Certification Center
Comment
Comparable to the existing access
method ‘L’
Detailed current job information upon
user request (e.g. position in queue)
Current job status without polling. No
detailed information (position in queue)
B+C
Current device information available (e.g.
for alerts in R/3), otherwise as A
E+B
C+E
Complete support
16
BC-XOM INTERFACE DOCUMENT
The use of the callback interface requires additional support in the OMS, since the OMS must provide an
active component (client) which passes events asynchronously to the R/3 System. The mechanism for this
is the Remote Function Call (RFC) of R/3 (see 3.3).
Each R/3 printer that is to be driven with access method E must have an LOMS assigned to it. The LOMS
determines the commands with which the ROMS is accessed (see 2.5)
Further, each printer is assigned to an SWP. Output requests for this device are passed to the ROMS by
way of this SWP and its instance.
If callbacks are to be used, then it is desirable to be able to distribute the processing load over multiple R/3
instances. Updating status information continues to be associated with significant database activity, and it is
therefore sensible to have callbacks processed by an instance that has rapid access to the database (ideally,
one which is local to the database computer). For this purpose, the LOMS data record also contains a
specification for the instance to be used for callbacks.
2.4 Reply Message Groups (RMG)
The interface as described foresees three kinds of feedback to the R/3 System. These are the following:
1. Device polling is carried out by the SWP that manages the device. Relevant feedback for the SWP
includes only jobs that were passed to the OMS by the SWP itself. Since a single OMS device may be
assigned to multiple R/3 devices which are managed by different SWPs, the specification of the OMS
device is not sufficient for selecting the jobs that are to be returned.
2. Job callbacks are performed for all jobs of an R/3 device to which an LOMS is assigned in which job
callbacks are activated. The LOMS determines the target for the callbacks.
3. Device callbacks are performed for all devices of an OMS for which an R/3 device is defined to which an
LOMS in which callbacks are activated is assigned. The LOMS determines the target for callbacks.
Various devices of an OMS can have differing callback targets, depending upon the configuration.
However, a single device can also have several targets.
For every callback, a classification of the callback will be made according to the target of the callback. This
classification suggests the need for the concept of a reply message group. Each job and each R/3-OMS
device is assigned to a RMG that is unique system wide. The RMGs are delivered with every job submit and
must be used as follows:
1. Device polling
In addition to the device, the command line specifies a (in this case SWP-specific) RMG; only information
on R/3 jobs with this group ID will be returned.
2. Job callback
R/3 will make an RFC function for querying the configuration of RMGs available. This function will return
a table with the RMGs used by the R/3 System and the required callback targets and parameters (e.g.
time interval, event count). In R/3, the RMGs for callbacks derive directly from the LOMS. The RMG of a
job thereby also allows determination of the callback target.
Alternatively, the required parameters (callback target, time interval etc.) can be passed to the OMS with
the SUBMIT of a job, so that for the pure job callback functionality the need for a configuration call is in
this case obviated.
In every case, the collection of events for each RMG must occur separately; The RMG parameter is
therefore not optional (see 2.6.3). Distinction by the target of a callback is not sufficient, since the
grouping of printers in a LOMS is independent of targets. The same target can be used for a large group
of ‘unimportant’ and for a small group of ‘important’ printers. In this way, the processing load can be
reduced though the same callback target is used. Such a configuration is not possible if the callback
target is the collective criterion.
If the callback information of the job submit is used, the callback targets for successive jobs of an RMG
can differ. In this case the callback client is free to choose any of those return addresses. Maybe the
newest one is the best choice.
3. Device callback
In addition to the configuration of the RMGs, a further RFC function will be made available to the OMS
client for querying the OMS devices that are used by the R/3 System and the RMG assigned to them.
The RMG can then be used to determine the callback target of a device.
SAP Integration and Certification Center
17
BC-XOM INTERFACE DOCUMENT
The RMGs for the polling process and for callbacks are different. Together with the transmittal of a job to the
OMS, the RMG that is to be used will be specified; this means the RMG to use is transparent to the OMS,
without respect to the process that is to be used. Whether to use callback or polling can be determined by
the callback target address, which is ‘-‘ for polling and a SAP instance name otherwise.
2.5 Command Line Interface
The existing method of specifying a print command in one (instance-specific) profile parameter has been
improved upon. In the new interface, the possible command templates are stored in the database and can
be modified at runtime. The R/3 system does not have to be restarted to change a command template, as is
currently the case
In R/3, the model commands you use are defined in table TSPCMDS:
*LNAME
*OPSYS
*LCMD
CMD
Char(6)
Char (10)
Char (6)
LOMS
Platform operating system
Logical command name
The logical command names currently defined are:
SUBMIT
DPOLL
(device polling)
DQUERY (device query)
CANCEL
JQUERY (job query)
Char (132) Command format
Each LOMS may use a different command set. To reflect the fact that the individual R/3 instances of an R/3
System can run on different platforms and that LOMS are not linked to a single SWP, the commands can
also be configured platform-dependently.
The following commands can be defined for each LOMS (and platform):
 SUBMIT
Transmit a job from the SWP to the OMS.
 DPOLL
Polling command of the SWP for querying previously submitted jobs at a device (corresponding to RMG).
 DQUERY
This function interactively to queries the entire queue (named global device query).
 CANCEL
Delete a job at the request of the user.
 JQUERY
Return full information on the jobs concerned.
2.5.1 General Requirements
2.5.1.1 Arguments
All arguments are parsed by the shell. Unfortunately, escaping for special characters is handled differently in
UNIX and NT. Therefore the command line is created differently by R/3 depending on the operating system:
UNIX: The characters \, `, “ and $ are escaped with \ (A single \ is represented as \\ ). Parameters which may
contain any shell special characters or blanks should be enclosed in double quotes (“) in the command
template (e.g. title).
NT: “ is escaped with \. All \’s are escaped if they occur before a “. % is translated into #. Arguments with
special characters or blanks should be enclosed in double quotes (“).
SAP Integration and Certification Center
18
BC-XOM INTERFACE DOCUMENT
2.5.1.2 Results
Results and/or messages from commands are expected in the standard output data stream of the OMS
command. The output must be line oriented. Its format is defined by this interface description. Other output
for the standard output data stream is not allowed and leads to a malfunction of the interface. Each line may
consist of several data fields. Data fields in output lines must be separated by white spaces. To allow later
improvements of the answer format each result format of an OMS command contains a version string. It is
the first field of the first line of the output.
For the formats described in this interface description the version string is ‘2.00’. It will be accepted
with R/3 release 4.0A. The old format ‘1.10’ will still be accepted by newer R/3 releases.
Return values from the OMS that cannot be made available by the OMS should be represented by a dash (). Blanks within output fields have to be escaped by \. A single \ is represented as \\. Results marked by an
asterisk (*) in the tables below are absolutely necessary. Trailing optional result values can be omitted.
Output is expected to be in the system character set of the calling R/3 instance.
2.5.1.3 Messages
If a message is part of a format of an output line, the last fields of the line will be used for the message. A
message needs up to 11 additional fields. The first field of the message fields contains the default message
translation.
If the message is not language-independent the other message fields can be omitted (Note: Trailing optional
result values can be omitted).
If the message should be language-independent additional fields are required: the company identifier and
the message identifier. Still optional are the arguments. Each argument consists of 2 fields: first the
argument text and then its argument type. Trailing arguments may be omitted. If there are no more
arguments and the type of the last argument is ‘C’ for string, the type may also be omitted. For argument
types refer to the XMI documentation.
The new format 2.00 is generally compatible with 1.10 because the message is the last component and the
default message text is the first field of the message fields. If the command delivers only languagedependent messages nothing needs to be changed.
The only exception is the device query command. Here in 1.10, the message is in the middle of the output
fields. This has been changed in 2.00. Now, for all commands, messages are always at the end of an output
line format. The command must be changed in any case.
The escaping for multi-byte characters has to be done for each byte separately because the parsing
algorithm has no special support for multi-byte characters. For arguments only names should be used (like
device or queue names). Messages like ‘Error &1’ with &1 = ‘out of paper’ should NOT be used. Instead use
separate messages with fixed meanings.
2.5.1.4 Response time
All commands must respond within a short period of time (e.g. 20 sec) and return to the caller. If the
command can not be executed within that time it must return with an error (e.g. job not accepted,
query can return incomplete lists (see table 4)).
2.5.2 Job Submission
The following data can be passed from R/3 to the command (the command syntax is not defined). A single &
must be represented by &&. (* Denotes a required parameter.)
SAP Integration and Certification Center
19
BC-XOM INTERFACE DOCUMENT
Table A:
Attribute
SAP spool ID*
Reply message
group *
Destination*
Document*
Parameter Meaning
name
&EI
Internal spool ID. Required by R/3 during the callback
as the return parameter for identifying the SAP job.
&EG
ID of an RMG. This information is required during
polling or callback for classification of the information to
be returned.
&P
Device of the OMS.
&F
Full name of the file that contains the print data
Attributes required if callback is controlled via the command line:
SAP instance
&ES
SAP instance name for callback in the format
<hostname>_<system ID>_<system number>
‘-‘ if no callback wanted.
Interval
&ET
Max. time from event for RMG to callback
Amount
&EA
Max. number of events up to callback for RMG
Optional attributes:
SAP client
SAP client
SAP user
SAP user
SAP user
Division
Job name
Job name
Title
SAP printer
Layout
Copy count (*)
Priority
Title page
Title page
Fax number
Fax person
R3LOMS flags
LOMS flags
R3ROMS flags
ROMS flags
ROMS name
LOMS name
System Id
Device name
Doc. Category
Printer driver
Path
File
Page Area
Name – Suffix
Page Number
Spool request No.
Output request No.
&M
&m
&O
&o
&R
&D
&I
&J
&T
&S
&L
&C
&Y
&U
&H/x/y/
&t
&EP
&E1
&E2
&E3
&E4
&Er
&El
&Es
&S
&d
&l
&p
&f
&r
&s
&c
&N
&n
Client of user who owns the job
Client of user who is printing
(SAP) name of the owner
(SAP) name of the user, who created the output request
(SAP) name of the receiver of the output
Division of receiver
Job name (SAP-internal) without DB-ID
Job name (SAP-internal) including DB-ID
SAP title
Short Name of the SAP printer
Layout format
Number of copies
SAP priority (1-9) 1 meaning high
Title page wanted? (X = yes, N = no)
x if title page wanted, y otherwise (x,y are strings)
Valid tel. no. for LOMS
Name of FAX recipient (future enhancement)
R/3 flags of the LOMS
LOMS configuration by OMS
R/3 flags of the ROMS
ROMS configuration by OMS
Name of real OMS
Name of logical OMS
ID of the calling R/3 system
Short-name of the device
Document category (as of kernel 4.6d)
Printer driver (as of kernel 4.6d)
Path of the file that contains the print data
Name of the file that contains the print data
Page area (as of kernel 4.6d)
Spool request name - suffix 2
Number of pages
Number of SAP spool request
Number of output request for spool request
Example: The submit command template (in UNIX) could look like this:
sap_submit &P &F &EI &EG &ES &ET &EA "&T" &C
SAP Integration and Certification Center
20
BC-XOM INTERFACE DOCUMENT
The substituted command line looks like this:
sap_submit printer /some/filename 123456789012345 reply_group
hostname_SID_no
10 100 "some title" 2
The LOMS flags option (&E2) or the ROMS flags option (&E4) can be used to pass OMS specific options not
configurable directly in the R/3 system. This could be an external domain, parameters required to connect to
an OMS server or additional job options valid for a whole group of (R/3) devices like a retention period.
The submit command delivers an output line in the following format:
Table B:
Field
Version*
Class code*
Area code*
OMS spool ID*
Message
Meaning
format x.xx (major / minor number)
Table 1
Table 3
Unique ID generated by the OMS if job is accepted, otherwise ‘-‘
SAP will only store 20 characters for that information!
Optional message from the OMS (see 2.5.1.3 (Message))
Example for the output:
2.00 1 1 - An\ error\ happened
or:
2.00 4 1 roms:0912345 Optional\ message\ on\ success
2.5.3 Device-Polling
The command needs at least two parameters (&P, &EG or &EL):
Table C:
Attribute
Destination*
Reply message
group(*)
Job ID(*)
Parameter name Meaning
&P
Log. device of the OMS
&EG
ID of an RMG (see submit)
&EL
List of OMS job IDs, which is separated by
spaces
It reports a brief status information for the jobs at the specified device which either match the RMG or the job
ID’s. Only those jobs should be reported. Only one of the possibilities (&EG or &EL) need to be supported.
The &EG option should be preferred, because the &EL option could lead to very long command lines. If the
list is too long the command line has to be split into several separate command executions. This is very
expensive and time consuming, so that the &EG version of the polling command should be supported if
possible.
At some point in time the device-polling command has to return a job state code of either 04,05 or 06
on every job that was accepted by the OMS. It is not tolerable that a job just leaves the system
without returning some kind of completion message to the application.
Finished jobs should be reported only once or at least only some few times because all output lines are
parsed and evaluated for each call. To determine whether a job should be reported or not the job retention
period is not suitable. A finished job should be reported once independently of the retention period, it may be
too long or more important too short.
Example:
sap_dev_poll &P &EG
SAP Integration and Certification Center
21
BC-XOM INTERFACE DOCUMENT
The substituted command line looks like this:
sap_dev_poll printer reply_group
sap_dev_poll &P &EL
becomes:
sap_dev_poll printer 1234 5678
The command returns the following output format:
1st line: Device status
Following lines: Status of an output request at the device.
Format of the device status line:
Field
Version*
Device state
code*
Class code*
Area code
Message
Meaning
Format x.xx (major / minor number)
Table 4
Table 1
Table 3
Detailed information, uninterpreted but logged by R/3 (see 2.5.1.3
(Message))
Format of the job status lines:
Field
SAP spool ID*
Job state code*
Class code*
Area code
Result code
Queue position
Message
Meaning
Internal spool ID of calling R/3
Table 5
Table 1
Table 3
Table 6
Pos. in queue (0 = active)
Detailed information, uninterpreted, but logged by R/3 (see 2.5.1.3
(Message))
Example: The output could look like (one line per job):
1. line: 2.00 XX.X000012 4 1 Everything\ ok
2. line: 123456789000001 2 4
3. line: 453434567000001 2 4
4. line: 123456789000002 3 4 3 - 0 Printing\ on\ LPT1
This list should contain only the requested jobs; there may be other jobs in the device queue: other R/3 jobs
from the same R/3 system but with a different RMG, jobs from other R/3 systems or non-R/3 jobs. The queue
length reported in the device status line should include all jobs in the device queue.
The polling interval could be set with SAP system profile-parameter "rspo/rspoget2/min_alarm_intervall".
Polling interval in seconds is (int(n/60)+1)*60, where n is the value of the profile-parameter. Minimum value
for polling interval is 60 seconds. Changes apply not before restart of SAP instance.
2.5.4 Device Query Command (User-Controlled)
This command should return all jobs in the device queue. For jobs submitted by R/3 systems it should report
the SAP spool id. For jobs submitted by other sources (non R/3 systems) a dash should be reported instead
of an SAP spool id. It is still possible to omit the sap spool id for other R/3 systems. If the SAP spool id is
reported then the RMG should also be reported.
SAP Integration and Certification Center
22
BC-XOM INTERFACE DOCUMENT
The command has at least one parameter:
Attribute
Parameter
name
&P
&Es
Destination*
System id
Meaning
Log. device of the OMS
ID of the calling R/3 system
Example:
sap_dev_query &P
The substituted command line looks like this:
sap_dev_query printer
The command returns the following output format:
1st line: Device status
Following lines: Status of an output requests at the device.
Format of the device status line:
Field
Version*
Device state
code*
Class code*
Area code
Message
Meaning
Format x.xx (major / minor number)
Table 4
Table 1
Table 3
Detailed information, uninterpreted, but logged by R/3 (see 2.5.1.3
(Message))
Format of the job status lines:
Field
SAP spool ID(*)
Job state code*
Class code*
Area code
Result code
Queue position
RMG(*)
OMS job ID
Job size
Job priority
Job name
Job comment
Message
Meaning
Internal spool ID of calling R/3; ‘-’ if no R/3 job
Table 5
Table 1
Table 3
Table 6
Pos. in queue (0 = active)
Reply Message Group of the job (‘-‘, if no R/3 job)
Internal ID of the OMS for the job
Size (in octets)
Priority of the job in the OMS
Name of the job in the OMS
Comment field of the OMS
Detailed information, uninterpreted, but logged by R/3 (see 2.5.1.3
(Message))
The reply should look like:
1.
2.
3.
4.
line: 2.00 XXX.000003
line: 12345 2 4 2 - 2
line: 2 4 2 - 1
line: 1453 3 4 2 4 0
4
roms:018436 8653 10 job\ name job\ comment message
3462 20 job_name job_comment message\ with\ \\\ ok
roms:043854 4536 8 job_name job_comment message
It may happen that an external output device is used by several R/3 output devices belonging to different
LOMSs, some allowing a device query, some not. Device queries are only possible for R/3 devices. An R/3
device will be mapped to the external output device name before executing the query command. In the
above case it is only possible to query the queue for R/3 devices belonging to a LOMS allowing a device
SAP Integration and Certification Center
23
BC-XOM INTERFACE DOCUMENT
query. This is already checked by the R/3 system before executing the command. It is not required for the
command to check this.
For all R/3 jobs the SAP spool id and the RMG have to be reported.
2.5.5 Cancellation
Command arguments:
Attribute Parameter
name
Job ID
&EL
Meaning
List of OMS job IDs, which is separated by spaces
For every job, the command delivers (in the order of the job IDs) output lines in the following format:
Field
Version*
Job state code*
Class code*
Area code
Result code
Message
Meaning
Format x.xx (major / minor number)
Table 5
Table 1
Table 3
Table 6
Detailed information, uninterpreted,, but logged by R/3(see 2.5.1.3
(Message))
It may happen that an LOMS specifies that a job cancellation should not be possible for a given job. This is
already checked inside R/3. It is not required for the job query command to check this.
The reply should look like: 2.00 2 4 2 0 message
2.5.6 Job query
Command arguments:
Attribute Parameter
name
Job ID
&EL
Meaning
List of OMS job IDs, which is separated by spaces
For every job, the command delivers (in the order of the job IDs) output lines in the following format:
Field
Version*
Job state code*
Class code*
Area code
Result code
Queue position
Pages printed so
far
Estimated wait
time
Message
Meaning
Format x.xx (major / minor number)
Table 5
Table 1
Table 3
Table 6
Pos. in queue (0 = active)
Pages already printed
Estimated time (in seconds) until printout is complete
Detailed information, uninterpreted, but logged by R/3
(see 2.5.1.3 (Message))
The reply should look like: 2.00 2 4 2 0 - - - message
SAP Integration and Certification Center
24
BC-XOM INTERFACE DOCUMENT
2.6 Callback Interface
The callback interface is used for asynchronous update of status information within the R/3 System. It
therefore replaces the polling interface, allowing the most up-to-date status information possible to be
received with minimum expenditure.
The activity must come from the OMS in which the relevant events occur, so that a command interface
cannot be used. Instead, the OMS manufacturer must deliver an additional active component (client), which
transmits the required information to the R/3 System on time. Here, the Remote Function Call (RFC) is used
as the interface. The OMS collects several events and signals with a single callback. This is required in order
to reduce the number of callbacks and the overhead involved with the RFC calls.
2.6.1 General design
To support the R/3 callback interface, each ROMS must provide a client. This client can be used for more
than one R/3 System (as customers generally have more than one R/3 System, which is test, consolidation
and production systems). Printers should be useable from all systems. Alternatively, the OMS can provide a
separate callback client for each R/3 System.
If only job callback is supported, all the required parameters (except for RFC user, password, client and
language) can be passed in the SUBMIT command. In this case, client configuration is not necessary.
If, however, configuration is supported, an OMS client must contain various configuration components:
1. Configuration of the R/3 Systems supported
2. Configuration of the RMG of the R/3 Systems supported
3. Configuration of the OMS devices, for which a callback is to take place
The information for number 1 must be passed to the client (see 2.6.1.1). The additional information for
numbers 2 and 3 is then requested at the R/3 Systems by RFC (see 2.6.2.1). As changes to configuration
are also possible while the R/3 System is running, dynamic reconfiguration of an active client must be
supported (see 2.6.2.3).
2.6.1.1 Configuration of the OMS client
When an R/3 System is started, it should be automatically ensured that the OMS client required is available
when callback operation mode is used, and that it is informed that this R/3 System exists. A start command
is declared within the R/3 System for every ROMS. Depending on whether the client can support multiple R/3
Systems the following two cases must be distinguished:
1.
Only one R/3 System is supported by the client:
a) If no client for the calling R/3 System is configured a new client has to be started.
2. Support for multiple R/3 Systems:
a) An OMS client must be started if none is running.
b) If the client is not configured for the calling R/3 System, the command must instruct that it is
reconfigured for the R/3 System.
Other client configurations are possible, i.e. one client per application server with a spool service. They have
to be handled adequately.
The client must remember for which R/3 Systems it is responsible, so that it can do a
reconfiguration for every R/3 System when the client is restarted. This implies that the client has to
be restarted automatically whenever it crashes.
SAP Integration and Certification Center
25
BC-XOM INTERFACE DOCUMENT
It must be possible to support multiple R/3 systems at the interface level.
In every case the start command must report the status of the client. The status line has the following
format:
Field
State*
Message
Meaning
= 0 o.k., != 0 error
Optional message from the OMS (see 2.5.1.3 (Message))
This command can be supplied with all the necessary parameters for opening an RFC connection to the R/3
System that is SAP System name, host name, instance ID, user, client, password and language. System
name (e.g. C11) specifies the R/3 System for which the client should be responsible. Host name and
instance ID (together with the system name) specifies the initial target for the first configuration calls
(SXMI_XOM_RMGS_QUERY + SXMI_XOM_DEVICES_QUERY).
User, client, password and language must be used as logon information for all connections to this R/3
System. If using the command line arguments they are delivered in the system code page of the R/3 system
A better and more secure solution would be a separate configuration file specifying all R/3 systems with the
logon information (username, password, and client) used for the corresponding R/3 system. The instance
information can still be part of the command line because this is no secret information. This file has to be
unreadable by normal operating system users. It can also be used to remember all R/3 systems a callback
client is responsible for. With this solution the startup command should be used to notify the client(s) about a
(possible) change of the configuration file. If a change is detected (comparing with the stored information in
the running client) the R/3 configuration calls have to be done for changed R/3 system entries and the logon
information has to be updated.
For the startup command there is a limited set of possible parameter substitutions:
Attribute
Parameter
name
R3ROMS flags &E3
ROMS flags
&E4
ROMS name
&Er
System Id
&Es
Meaning
R/3 flags of the ROMS
ROMS configuration by OMS
Name of real OMS
ID of the calling R/3 system
The command string is freely configurable in the R/3 ROMS definition so that you can use a syntax you want.
It should contain at least the above mentioned parameters. In addition any configuration parameters for your
client can also be specified.
The startup command could be for example:
oms_startup <system name> <host name> <instance ID> <user> <client>
<password> <language>
2.6.2 Configuration Interface
The configuration data for the RMG and the devices can be queried via additional RFC functions. This is
necessary when the client is started for the first time and when it is reconfigured.
SAP Integration and Certification Center
26
BC-XOM INTERFACE DOCUMENT
2.6.2.1 RMG configuration
The RFC SXMI_XOM_RMGS_QUERY requires the following arguments:
Field
Data type Meaning
ROMS Char (10) OMS, for which information is required.
The RFC delivers the following results:
Field
Data type
Meaning
REPLY_GROUP Table
List of RMGs
S
(SEXT_RMGCF)
RECONFIG
Numc (3)
Reconfiguration in seconds (see 2.6.2.3
(Reconfiguratio))
R3FLAGS
Char (60)
Options for ROMS configuration (see 2.2.2)
OMSFLAGS
Char (60)
ROMS configuration by OMS
The structure SEXT_RMGCF has the following format:
Field
Data type Meaning
RMGID
Char(20)
ID of the RMG
CALLBTRGT
Char(40)
SAP instance (target for callback) (format as &ES for
submit)
JCALLBIV
Numc(3)
Time interval for collection (in seconds)
JCALLBAMNT
Numc(3)
Max. buffering (number of events for jobs)
DCALLBIV
Numc(3)
In seconds
DCALLBAMNT
Numc(3)
Max. buffering (number of events for device)
RETRYIV
Numc(3)
Reconnection attempt (in seconds) (see 2.7.2)
R3FLAGS
Char(60)
Options for LOMS configuration (see 2.2.1)
OMSFLAGS
Char(60)
LOMS configuration by OMS
ROMS_UNKNOWN will be returned as an exception if the ROMS is not known by R/3.
Connections to the callback targets can be opened right after the reception of this list or when the first
callback to an unconnected target should be made. To each target only one connection should be opened.
The initial connection has to be left open and can be used as an additional target (see 2.7.1). Broken initial
connections should be rebuilt when needed but only in reasonable time intervals (e.g. use
max(min(RETRYIV), RECONFIG)).
Note 1: There may be several RMGs which refer to the same target.
Note 2: Normally the initial connection should be used for reconfiguration calls, if however the initial
connection goes down any other connection may also be used for a reconfiguration.
In the event of a reconfiguration existing connections should be reused (close/open sequences should be
avoided). Connections which are no longer used in the new configuration should be closed.
2.6.2.2 Device configuration
The RFC SXMI_XOM_DEVICES_QUERY requires the following arguments:
Field
Data type Meaning
ROMS
Char(10)
OMS, for which information is required.
The RFC delivers a table DESTINATIONS (SEXT_DEVCF) with the following line format:
Field
Data type Meaning
DEST
Char(80)
Device of the OMS
RMGID
Char(20)
ID of the RMG for the device
ROMS_UNKNOWN will be returned as an exception if the ROMS is not known by R/3.
SAP Integration and Certification Center
27
BC-XOM INTERFACE DOCUMENT
2.6.2.3 Reconfiguration
The requirement that the client be reconfigured is transmitted with every callback call. If there are no events
for signaling for a long time period, the client must transmit empty signals at particular time intervals in order
to request information as to whether a reconfiguration is necessary. The interval duration for this check is
transmitted to the client through the R/3 System during RMG configuration (RECONFIG). Reconfigurations
should only be done when indicated by the return value of the callback.
The callbacks for jobs and devices deliver the following results:
Field
CONFIG_GROUPS
CONFIG_DEVICES
CALLBACK_INTERVAL
Data
type
Char (1)
Char (1)
Char (3)
CALLBACK_AMOUNT
Char (3)
Meaning
X = group reconfiguration necessary
X = device reconfiguration necessary
Maximum time (in seconds) for buffering events. A
call should be made after this time if there are any
events to deliver.
Maximum number of events to be collected. More
events can however be delivered during callback.
This call can return an exception ROLLBACK. Which means that the R/3 system was not able to process the
returned information. The OMS callback client should repeat transmission after the RFC retry time interval
(see 2.6.2.1(
SAP Integration and Certification Center
28
BC-XOM INTERFACE DOCUMENT
RMG configuratio) ).
A callback should thus be made when one of the following conditions is true:
1. The CALLBACK_AMOUNT is reached.
2. The CALLBACK_INTERVAL has expired and there are buffered callback events to deliver.
All events which have been accumulated at the time of the callback should be returned with one call
even if the sum is greater than CALLBACK_AMOUNT.
When passing the configuration values for the job callback via the command line for job submit, these return
values can be ignored if device callback is not used.
2.6.3 Callbacks
Callbacks are used to deliver status information as events concerning output devices or jobs from the
external output management system to the R/3 system. Both callback functions return reconfiguration
information and take a table with event entries. Each event has a time stamp indicating the time when the
event occurs. The time stamps must be UTC time stamps!
2.6.3.1 Report Levels
Using the callback interface it is possible a send events for nearly everything that happens to a job or device.
But unfortunately the more events are sent the worse the performance. So it may be useful to control the
amount of events. This can be done by using a report level for every RMG. The level can be configured
together with the configuration of logical output management systems inside R/3.
There are several levels (see table 2) defined by R/3, but there may be additional levels defined by the
output management system. Higher levels include the events of lower levels.
Even if the lowest level is specified there are some kinds of events that have to be delivered under all
circumstances. These are the completion events. Whenever a job is completed by the output management
system (successfully printed or with an error state), this event must be delivered to the R/3 system.
SAP Integration and Certification Center
29
BC-XOM INTERFACE DOCUMENT
2.6.3.2 Event Messages
Each entry contains a message structure for language-independent messages. A message structure
consists of the following fields:
Field
MSGCLASS
MSGID
MSGARG1
ARGTYPE1
MSGARG2
ARGTYPE2
MSGARG3
ARGTYPE3
MSGARG4
ARGTYPE4
MSGTEXT
Data type
Char(16)
Char(30)
Char(128)
Char(1)
Char(128)
Char(1)
Char(128)
Char(1)
Char(128)
Char(1)
Char(128)
Meaning
Company name range
Company name range private message id
Argument string for the first argument
Argument type for the first argument
Argument string for the second argument
Argument type for the second argument
Argument string for the third argument
Argument type for the third argument
Argument string for the fourth argument
Argument type for the fourth argument
Default translation of the message
2.6.3.3 General Exceptions for RFC Calls
The following exceptions may occur:
Exception
NOT_LOGGED_ON
CANT_LOG_ACTION
Meaning
There is no logon to the SMAPI XOM
The action was terminated because the R/3 XMI logging
mechanism returned an error
2.6.3.4 Job Callback
The RFC callback for job events SXMI_XOM_JOBS_CALLBACK requires the following arguments:
Field
RMG_ID
JOB_EVENT
S
Data type
Char(20)
Table
Meaning
RMG of the confirmation
Table of events that have occurred
The table JOB_EVENTS has structure SXOM_JOBEV with the following fields:
Field
SPOOLID*
TIMESTAMP*
JOBSTATE*
CLASSCODE*
AREACODE
RESULTCODE
QUEUEPOS
PPAGES
WAITTIME
MESSAGE
Data type
Char(15)
Char(14)
Numc(2)
Numc(2)
Numc(2)
Numc(2)
Numc(4)
Numc(6)
Numc(4)
Meaning
Internal spool ID in R/3
YYYYMMDDHHMMSS UTC time of event
Table 5
Table 1
Table 3
Table 6
Pos. in queue (0 = active)
Pages already printed
Estimated time (in minutes) until printout is complete.
Detailed info, uninterpreted, but logged by R/3 (see 2.6.3.2)
At some point in time the callback client must return a job state code of either 04, 05 or 06 on every
job that was accepted by the OMS. It is not tolerable that a job just leaves the system without
returning some kind of complete message to the application.
SAP Integration and Certification Center
30
BC-XOM INTERFACE DOCUMENT
This call can return an exception ROLLBACK. Which means that the R/3 system was not able to process the
returned information. The OMS callback client should repeat transmission after the RFC retry time interval
(see 2.6.2.1).
If the client recognizes that its internal event queue (according to the current report level) is constantly
growing because the transmission to the R/3 system is too slow, it should decrease the report level by 1 until
the queue is drained. (Possibly comparing the delivery rate in the past and the current event rate is helpful in
deciding what report level is appropriate.)
2.6.3.5 Device callback
The RFC callback for device events SXMI_XOM_DEVICES_CALLBACK requires the following arguments:
Field
RMG_ID
DEVICE_EVENTS
Data
type
Char(20)
Table
Meaning
RMG of the signal
Table of events that have occurred
The table DEVICE_EVENTS has structure SEXT_DEVEV with the following fields:
Field
PRTLIST*
TIMESTAMP*
DEVSTATE*
CLASSCODE*
AREACODE
MESSAGE
Data type
Char(254)
Char(14)
Char(30)
Numc(2)
Numc(2)
Meaning
List of relevant OMS devices, which is separated by spaces
Format: YYYYMMDDHHMMSS UTC time of event
Table 4
Table 1
Table 3
Detailed info, uninterpreted, but logged by R/3 (format see
2.6.3.2)
If not all the affected printers can be returned in one table line, the callback client must use multiple lines.
2.6.3.6 Logging Event Messages in XMI
Logging Event Messages in XMI is specified in the SAP System with entries in the TSPOPTIONS table.
Make the following entry "XMILOGLEVEL" in the table "TSPOPTIONS" with value "0", "1" or "2". Changes
apply not before restart of callback target.
Field
SPOPTION
VALUE*
Data type Value
Char(16) XMILOGLEVEL
Char(200) 0
1
2
Meaning
no job-event information
all calls
full information
2.7 Callback Target (SAP Instance) Does Not Respond to RFC Callback
If the target for an RFC callback is down, the RFC will not be answered by R/3. The client should try to
reestablish the connection after the time interval specified in the LOMS definition (RFC retry) until successful
reconnection to the target. The reconnection retry must be stopped if an RMG reconfiguration has invalidated
that target in the meantime.
Two cases must be distinguished:
SAP Integration and Certification Center
31
BC-XOM INTERFACE DOCUMENT
2.7.1 At least one alternative target is still up
If there are other active callback targets for the same system, then the client should redirect events up to
report level 2 to any of these destinations. Events below level 2 can be discarded in this case. The client
should however try to reestablish the connection to the original callback target.
There are two possibilities for determining an alternative callback target:
1. Using a configured target
a) The system name is specified with the job or event.
In this case all callback targets returned by the corresponding SXMI_XOM_RMGS_QUERY for this
system can be used as an alternative.
b) The system name is not specified with the job or event.
Extract the system name from the current callback target (structure of SAP instance is defined in
parameter &ES for job submit, see 2.5.2) and proceed as in point a).
If the RMG is not known in the callback client a reconfiguration should be done. If the RMG is still
unknown after the reconfiguration no callback should be made.
2. Using the initial connection
As already mentioned in 2.6.2.1 the initial connection can also be used for callbacks.
2.7.2 All targets are down
In this case the OMS callback client should store all information until the R/3 instance is up and
running again. The client may restrict the logging of events for jobs to final complete states (with or without
error). The client should retry sending this undelivered information after the time interval specified in the
LOMS definition (RFC retry). In principle, any target can be used for the callback, but the original target
should be preferred if the connection is up again.
2.8 RFC Server Interface
The goal of the RFC server solution is to replace the command line interface with a complete RFC interface
for command request and callbacks. Therefore the OMS must provide an RFC server that implements the
RFC functions call form the SAP system. There are RFC functions for the commands of the command line
interface. The meaning still keep the same. Please refer to section 2.5 for further details. This section
summarized the interface details for the RFC version of the OMS specification
RFC Server interface is available with SAP Kernel 4.6D and 6.20 with dedicated patch level. Please note that
the RFC Server Interface applies not for certification. Please refer to SAP Note 571534 and 571175 for more
details.
2.8.1 General design
To support the RFC Server interface, each ROMS must provide a server. This server can be used for more
than one R/3 System (as customers generally have more than one R/3 System that is test, consolidation and
production systems). Printers should be useable from all systems. Alternatively, the OMS can provide a
separate server for each R/3 System.
For configuration, the OMS server must contain various configuration components:
1. Configuration of the R/3 Systems supported
2. Configuration of the RMG of the R/3 Systems supported
3. Configuration of the OMS devices, for which a callback is to take place
SAP Integration and Certification Center
32
BC-XOM INTERFACE DOCUMENT
The information for number 1 must be passed to the OMS server at startup or at requested reconfiguration
(see 2.8.1.1). The additional information for numbers 2 and 3 is then requested at the R/3 Systems by RFC
(see 2.6.2.1). As changes to configuration are also possible while the R/3 System is running, dynamic
reconfiguration of an active server must be supported.
2.8.1.1 Configuration of the OMS Server
When an R/3 System is started, it should be automatically ensured that the OMS server required is available,
and that it is informed that this R/3 System exists. A start command is declared within the R/3 System for
every ROMS. Depending on whether the server can support multiple R/3 Systems the following two cases
must be distinguished:
1. Only one R/3 System is supported by the server:
a) If no server for the calling R/3 System is configured a new server has to be started.
2. Support for multiple R/3 Systems:
a) An OMS server must be started if none is running.
b) If the server is not configured for the calling R/3 System, the command must instruct that it is
reconfigured for the R/3 System.
Other server configurations are possible, i.e. one server per application server with a spool service. They
have to be handled adequately.
The server must remember for which R/3 Systems it is responsible, so that it can do a
reconfiguration for every R/3 System when the server is restarted. This implies that the server has
to restart automatically whenever it crashes.
It must be possible to support multiple R/3 systems at the interface level.
In every case the start call must report the status of the server. The status line has the following format:
Field
State*
Message
Meaning
= 0 o.k., != 0 error
Optional message from the OMS (see 2.5.1.3 (Message))
This call can be supplied with all necessary parameters for opening an RFC connection to the R/3 System
for registration of the OMS server at the R/3 System. For the startup call there is a limited set of possible
parameters that is the ID of the calling R/3 system together with the Name of real OMS and the OMS flags of
the ROMS as RFC parameters, and host name and gateway number as command parameters (see
documentation for RFC API). These parameters specify also the initial target for the first configuration calls
for the OMS client with SXMI_XOM_RMGS_QUERY and SXMI_XOM_DEVICES_QUERY (see 2.6.2.1). The
OMS client has to be stared together with the OMS server. There is no separate call from R/3 System
to start OMS client.
The OMS_STATUS call gets the following arguments:
Field
ROMS
SYSID
PARAMS
Data type
Char(10)
Char(8)
Char(132)
Meaning
Name of real OMS
ID of the calling R/3 system
OMS start-up configuration by OMS
The OMS flags of the ROMS are freely configurable in the R/3 ROMS definition.
The RFC must deliver the following results:
Field
OMS_STATE
MESSAGE
Data type
Numc(3)
SXMIMSGRAW
Meaning
OMS status code
Message (Detailed info, uninterpreted, but logged by
R/3 (see 2.6.3.2))
SAP Integration and Certification Center
33
BC-XOM INTERFACE DOCUMENT
2.8.2 Job Submission
Previous versions of this documentation describe the 'data direct' method. The 'data direct' RFC interface to
an external OMS system is no longer supported. There is no longer the option of implementing an external
output management system (OMS) as an RFC server to send print data directly by RFC. The 'data per file'
option is still available. This applies retroactively to all releases in which this function was previously
available. See SAP Note 700571.
For job submission there is the possibility to use a local file for the submission. This does only work, if the
RFC server of the OMS is running on the same host as the spool work process (may be for single server
systems) or if the RFC server has access to the filesystems used by the SAP server. Another possibility
would be to use a common filesytem for the data transfer. All of these possibilities require special installation
efforts to achieve the accessibility of the job data.
Each of the three calls may return an error state. In this case the submission will be aborted and there will be
no further call for the same job.
2.8.2.1 Starting a job submission
The OMS_START_JOB call gets the following arguments:
Field
RMG_ID
LOMS
OSPRT
FILE
SPOOLPARAMETERS
Data
type
Char(20)
Char(6)
Char(50)
Char(254
)
Table
Meaning
Reply Message Group for the job
Logical OMS for the job
OMS printer name
Filename for the data transfer (empty, if streaming mode
shall be used)
Attribute list for the job
The table SPOOLPARAMETERS has structure SEXT_PARAM with the following fields:
Field
NAME
LINE
VALUE
Data type Meaning
Char(16) Attribute name
Numc(8) Line number in case of multi-line attributes starting with 1
(this field is not used so far, it is always zero)
Char(200) Attribute value. If multiple line specify the same attribute name
The attribute has multiple values.
SAP Integration and Certification Center
34
BC-XOM INTERFACE DOCUMENT
So far, the following spool parameters are transferred:
Attribute
SAP spool ID*
Parameter name
S_SPOOLID
Reply message
group *
S_RMGID
Meaning
Internal spool ID. Required by R/3 during the
callback as the return parameter for identifying
the SAP job.
ID of an RMG. This information is required
during polling or callback for classification of the
information to be returned.
Attributes present if callback is required:
SAP instance
S_CALLBTRGT
Interval
Amount
S_CALLBIV
S_CALLBAMNT
SAP instance name for callback in the format
<hostname>_<system ID>_<system number>
‘-‘ if no callback wanted.
Max. time from event for RMG to callback
Max. number of events up to callback for RMG
Optional attributes:
SAP client
SAP client
SAP user
SAP user
S_RQCLIENT
S_PJCLIENT
S_RQOWNER
S_PJOWNER
SAP user
Division
Job name
Job name
Title
SAP printer
Layout
Copy count (*)
Priority
Title page
Fax number
R3LOMS flags
S_RECEIVER
S_DIVISION
LOMS flags
R3ROMS flags
ROMS flags
DB location
S_JOBNAME
S_TITLE
S_DEVICE
S_LAYOUT
S_COPIES
S_PRIORITY
S_HOSTTITLE
S_TELENUM
S_R3LOMSFLAG
S
S_LOMSFLAGS
S_R3ROMSFLAG
S
S_ROMSFLAGS
S_DBLOCAT
Client of user who owns the job
Client of user who is printing
(SAP) name of the owner
(SAP) name of the user, who created the output
request
(SAP) name of the receiver of the output
Division of receiver
Job name (SAP-internal) without DB-ID
Job name (SAP-internal) including DB-ID
SAP title
Name of the SAP printer
Layout format
Number of copies
SAP priority (1-99) 1 meaning high
Title page wanted? (X = yes, N = no)
Valid tel. no. For LOMS
R/3 flags of the LOMS
LOMS configuration by OMS
R/3 flags of the ROMS
ROMS configuration by OMS
Location of database
Additionally the dynamic attributes of the spool request and the output request are appended. This section
will start with an attributes name 'S_DYNAMIC' and one of the two following values:
-
Start of output request parameters
Start of spool request parameters
SAP Integration and Certification Center
35
BC-XOM INTERFACE DOCUMENT
The RFC must deliver the following results:
Field
TMNID
Data type
Char(40)
CLASSCODE
AREACODE
MESSAGE
Numc(2)
Numc(2)
SXMIMSGRAW
Meaning
Transmission id for further calls belonging to the same
job submission
Table 1
Table 3
Message (Detailed info, uninterpreted, but logged by
R/3 (see 2.6.3.2))
2.8.2.2 Finish a job submission
If no error was reported during by any earlier call of a submission, the submission will be finished by a call of
OMS_FINISH_JOB. This call has to return the final submission state and the hostspool identifier for the new
job. The OMS_FINISH_JOB call gets the following arguments:
Field
TMNID
Data type
Char(40)
Meaning
Transmission id
The RFC must deliver the following results:
Field
JOBID
CLASSCODE
AREACODE
MESSAGE
Data type
Char(40)
Numc(2)
Numc(2)
SXMIMSGRAW
Meaning
Hostspool job identifier
Table 1
Table 3
Message (Detailed info, uninterpreted, but logged by R/3
(see 2.6.3.2))
2.8.3 Device Polling
For the RFC polling there are the same requirements as for the command line version (sew section 2.5.3).
The OMS_POLL_DEVICE call gets the following arguments:
Field
RMG_ID
LOMS
OSPRT
Data type
Char(20)
Char(6)
Char(50)
Meaning
Reply Message Group for the job
Logical OMS for the job
OMS printer name
The RFC must deliver the following results:
Field
DEVSTATE
JOBS
Data type
Char(30)
Table
(SEXT_PQUEU)
Meaning
See section 2.5.3
Job list (all pending jobs have to reported until a final state
was reported at least once)
SAP Integration and Certification Center
36
BC-XOM INTERFACE DOCUMENT
The table JOBS has structure SEXT_PQUEU with the following fields:
Field
SPOOLID*
JOBSTATE*
CLASSCODE*
AREACODE
RESULTCODE
QUEUEPOS
MESSAGE
Data type
Char(15)
Numc(2)
Numc(2)
Numc(2)
Numc(2)
Numc(4)
Meaning
Internal spool ID in R/3
Table 5
Table 1
Table 3
Table 6
Pos. in queue (0 = active)
Detailed info, uninterpreted, but logged by R/3 (see
2.6.3.2)
2.8.4 Device Query
For the RFC device query there are the same requirements as for the command line version (see section
2.5.4). The OMS_QUERY_DEVICE call gets the following arguments:
Field
LOMS
OSPRT
Data type
Char(6)
Char(50)
Meaning
Logical OMS for the job
OMS printer name
The RFC must deliver the following results:
Field
DEVSTATE
QUEUE
Data type
Char(30)
Table
(SEXT_QUEUE)
Meaning
See section 2.5.3
Queue entries for the device
The table QUEUE has structure SEXT_QUEUE with the following fields:
Field
SPOOLID*
JOBSTATE*
CLASSCODE*
AREACODE
RESULTCODE
QUEUEPOS
MESSAGE
Data type
Char(15)
Numc(2)
Numc(2)
Numc(2)
Numc(2)
Numc(4)
RMG(*)
OMS job ID
Job size
Job priority
Job name
Job comment
Char(20)
Char(40)
Numc(10)
Numc(4)
Char(105)
Char(105)
Meaning
Internal spool ID in R/3
Table 5
Table 1
Table 3
Table 6
Pos. in queue (0 = active)
Detailed info, uninterpreted, but logged by R/3 (see
2.6.3.2)
Reply Message Group of the job (‘-‘, if no R/3 job)
Internal ID of the OMS for the job
Size (in octets)
Priority of the job in the OMS
Name of the job in the OMS
Comment field of the OMS
SAP Integration and Certification Center
37
BC-XOM INTERFACE DOCUMENT
2.8.5 Job Cancellation
For the RFC job cancellation there are the same requirements as for the command line version (see section
2.5.5). The OMS_CANCEL_JOBS call gets the following arguments:
Field
JOBS
Data type
Meaning
Table
List of jobs to cancel
(SEXT_JCNCL)
The table JOBS has structure SEXT_JCNCL with the following fields:
Field
PJIDENT*
PJNUMBER*
JOBID*
LOMS*
VALID+
JOBSTATE
CLASSCODE
AREACODE
RESULTCODE
MESSAGE
Data type
INT4
INT2
Char(15)
Char(6)
Char(1)
Numc(2)
Numc(2)
Numc(2)
Numc(2)
Meaning
SAP Spool request id
SAP Output request number
OMS identifier of the job
Logical OMS of the job's device
Internal use for SAP
Table 5
Table 1
Table 3
Table 6
Detailed info, uninterpreted, but logged by R/3 (see
2.6.3.2)
The fields marked with an asterisks (*) are delivered by the SAP system. The RFC must add the contents of
the rest of the field. The valid field (+) must be updated by the RFC call, depending on the status of the query
call for this job. The following values are possible:
Value
<space
>
X
L
R
S
O
F
C
E
Meaning
Entry unprocessed, this is the initial value, it must be changed to one of the
following states.
Entry processed correctly.
LOMS not valid.
RFC problems
Not supported
The following values are set internally for the command line interface:
No state info delivered for these jobs. Used by the command line interface to
indicate a missing answer line in the output stream of the query command.
Format error.
No command configured
Command execution failed
SAP Integration and Certification Center
38
BC-XOM INTERFACE DOCUMENT
2.8.6 Job Query
For the RFC job query there are the same requirements as for the command line version (see section 2.5.5).
The OMS_QURY_JOBS call gets the following arguments:
Field
JOBS
Data type
Meaning
Table
List of jobs to be queried
(SEXT_JSTAT)
The table JOBS has structure SEXT_JSTAT with the following fields:
Field
PJIDENT*
PJNUMBER*
JOBID*
LOMS*
VALID+
JOBSTATE
CLASSCODE
AREACODE
RESULTCODE
QUEUEPOS
PPAGES
WAITTIME
MESSAGE
Data type
INT4
INT2
Char(15)
Char(6)
Char(1)
Numc(2)
Numc(2)
Numc(2)
Numc(2)
Numc(4)
Numc(6)
Numc(4)
RMGID
Char(20)
Meaning
SAP Spool request id
SAP Output request number
OMS identifier of the job
Logical OMS of the job's device
Internal use for SAP
Table 5
Table 1
Table 3
Table 6
Pos. in queue (0 = active)
Pages already printed
Estimated time (in minutes) until printout is complete.
Detailed info, uninterpreted, but logged by R/3 (see
2.6.3.2)
Reply Message Group for the job
The fields marked with an asterisks (*) are delivered by the SAP system. The RFC must add the contents of
the rest of the field. The valid field (+) must be updated by the RFC call, depending on the status of the query
call for this job. See the job cancel call for possible values.
SAP Integration and Certification Center
39
BC-XOM INTERFACE DOCUMENT
3. APPENDIX
3.1 Appendix A - Codes
Class Code (Table 1)
Status
Code
01
02
03
04
Meaning
Error
Problem requiring intervention
Problem not requiring intervention
Information (no error)
Callback Report Level (Table 2)
Status
Code
01
02
03
04
05
09
Meaning
Completion
Problem with intervention
Problem without intervention
Status change
Information (no error)
All available Information (as of
4.6)
Higher-number events include lower-number ones. Example:
02 includes 01.
Note: For every problem reported (class code 02 or 03) an equivalent ‘problem solved’ event must be
2
generated (class code 04) (e.g. ‘paper out’ and ‘paper refilled’ have to be reported). Only a general status is
held inside the R/3 system. If multiple problems are reported, the status code should always reflect the
overall status of the job or device. For example: If there are two different problems and one is solved, there
may be a separate solved message for this problem, but the code should indicate that there is still a problem.
It is not required to send multiple events if all problems are solved at the same time, but there must be at
least one positive event after all problems are solved.
Area Code (Table 3)
Status
Code
01 / 09
02
03 / 11
04 / 12
05
2
Meaning
Spooler
/ second value SWP
intern
Printing
Formatting
/ second value SWP
intern
Connection, network / second value SWP
intern
Other
Those different class codes for one report level are the reason for dividing the former table 1 in two separate tables.
SAP Integration and Certification Center
40
BC-XOM INTERFACE DOCUMENT
Device State Code (Table 4)
Status
Code
Char 1
Char 2
Char 3
Char 4
Char 5..10
Char 11
Char 12..30
Meaning
Queue enabled (flag)
Printing enabled, one of the printers can print and queue is not paused (flag)
Alarm (flag)
Printing right now, at least one of the physical printers, which can be reached
from the logical printer, is printing (flag)
Number of jobs in queue (leading 0’s, blanks = unknown)
‘X’ = incomplete state information, ‘ ‘ = complete state information
Reserved
Flags can have one of the following values:
‘X’ = true
‘ ’ or ‘.’ = false (if spaces are used, they have to be escaped in the output of the commands called via
the command line interface)
‘U’ = unknown
Job State Code (Table 5)
Status
Code
01
02
03
04
05
06
07
08
Meaning
Pre-processing, formatting
Pending, waiting in queue
Processing, printing
Complete, cannot be resubmitted
Retained, complete but still stored within
OMS
Canceled
Gone (no information for that job available)
Unknown (probably bad job id)
Result Code (Table 6)
Status
Code
01
02
03
04
05
Meaning
Comment
Printed
Not printed
Partly printed
Possibly
printed
Output
changed
Printed correctly
No printout
Output only partly generated, was canceled
Printout possibly generated
Output differs from intended format (e.g. font/character
replacement).
SAP Integration and Certification Center
41
BC-XOM INTERFACE DOCUMENT
3.2 Appendix B - Examples
SAP Instanz I2
SWP3
SAP Instanz I3
SAP-System C11
SAP Instanz I1
SWP2
R3LP3
CC11LOMS2
SAP Instanz I4
ROMS2
R3LP7
CC11LOMS3
LOMS3
R3LP6
CC11LOMS3
Callback
LP3
R3LP5
CC11LOMS2
LOMS2
LP2
R3LP4
CC11LOMS2
Callback
LP4
SWP1
ROMS1
LOMS1
Polling
R3LP2
PC11SWP1
LP1
LP1
PP4
PP6
LOMS2
Callback
R3LP3
CC12LOMS1
OMS2
CC12LOMS2 - LP3
(C12/I1)
CC11LOMS3 - LP1
(C11/I4)
- LP3
SWP1
SAP Instanz I1
R3LP2
CC12LOMS1
ROMS2
SAP-System C12
LP3
R3LP1
CC12LOMS1
Callback
LOMS1
ROMS1
LP2
PP5
42
SAP Integration and Certification Center
R3LP1
PC11SWP2
OMS1
CC11LOMS2 - LP2
(C11/I1)
- LP3
- LP4
CC12LOMS1 - LP1
(C12/I1)
- LP3
PP3
J3 CC11OMS2
PP2
J1 PC11SWP2
J4 CC12LOMS1
PP1
J2 CC12LOMS1
Figure 3: Possible Situation
BC-XOM INTERFACE DOCUMENT
Figure 3 shows a snapshot of a possible situation after 4 jobs have been submitted.
Job
J1
J2
J3
J4
submitted
to
R3LP1
R3LP1
R3LP5
R3LP2
SAP
System
C11
C12
C11
C12
Consider the following scenarios:
1. J1 finishes
J1 was submitted to R3LP1/C11. This is a member of a polling LOMS (LOMS1/C11), so SWP2/C11 will ask
for the status of this job by polling. The OMS does not need to deliver any callbacks in this case. It stores the
final state of the job until a polling request for RMG = PC11SWP2 and device LP1 arrives.
2. J2 finishes
J2 was submitted to R3LP1/C12, which belongs to LOMS1/C12. This LOMS is defined as type “callback”.
When J2 finishes, the OMS must either use the return address provided in the submit call for that job or look
at its internal table. This table specifies that RMG C12LOMS1 belongs to target C12/I1. A callback to C12/I1
is therefore made indicating that J2 has finished.
3. PP3 is out of paper
If PP3 runs out of paper, then the OMS1 must deliver a device callback for every logical OMS1 device which
can reach PP3. In our example this would be LP3 and LP4. By looking at its internal tables, the OMS1 can
determine the callback targets. In this example, the OMS1 must make 3 callbacks:
1. Callback for LP3 to C11/I1
2. Callback for LP4 to C11/I1
3. Callback for LP3 to C12/I1
The first to calls can be combines in a single callback since they have the same RMG
SAP Integration and Certification Center
43
www.sap.com
© 2013 SAP AG or an SAP affiliate company. All rights reserved.
No part of this publication may be reproduced or transmitted in any
form or for any purpose without the express permission of SAP AG.
The information contained herein may be changed without prior notice.
Some software products marketed by SAP AG and its distributors contain
proprietary software components of other software manufacturers. National
product specifications may vary.
These materials are provided by SAP AG and its affiliated companies (“SAP
Group”) for informational purposes only, without representation or warranty of
any kind, and SAP Group shall not be liable for errors or omissions with
respect to the materials. The only warranties for SAP Group products and
services are those that are set forth in the express warranty statements
accompanying such products and services, if any. Nothing herein should be
construed as constituting an additional warranty.
SAP and other SAP products and services mentioned herein as well as their
respective logos are trademarks or registered trademarks of SAP AG in
Germany and other countries.
Please see
http://www.sap.com/corporate-en/legal/copyright/index.epx#trademark
for additional trademark information and notices.