Almost all system services, except some filters, need one or more unique request codes, so that clients can make use of their services. The following sections describe how to define requests for a system service.
What You Need to Define
Before you can install your system service and let client applications begin using it, you must do two things. First, you must define your requests to the operating system, or it will not allow your service to serve them.
Second, if you use a procedural interface you must create an object file that defines the names of your requests for the client application.
Otherwise, the Linker will be unable to tie the symbolic name of your request to the operating system's request number.
To successfully define your requests to the operating system, you must perform the following three steps:
1. Choose your request codes. Requests that need a procedural interface must be defined in request level A, C, or E.
2. Define the format of your requests in a request definition text file (for example, ServerRequest.txt).
3. Create a binary request file (for example, ServerRequest.sys) from your request definition text file, using the Make Request Set utility.
4. Merge your binary request file with the operating system's request file, using the Install New Request utility.
For a client application to use your requests, you must also do the following:
1. Create a request label file that defines the procedure name for each of your request codes that has a procedural interface (for example, ServerRqLabel.asm) .
8-30 eTOS/Open Programming Practices and Standards - Part I
2. Assemble your request label file into an object file (for example, ServerRqLabel.obj).
3. Link or Bind the object file into the client application.
Both these procedures are described in the following sections.
Defining a Request
The request definition text file defines all aspects of your system service's requests. The following sections explain the items you need to define.
Listing 8-8 shows part of a sample request definition file. Each of the fields on the request definitions is defined below.
:WsAbortRq:OD905h
Writing Request-Based System Services 8-31
:ServiceExch:exchlnstalledMastr :sCntlnfo: 0
:nReqPbCb: 0 :nRespPbcb:l
:Params: p(12), c(2,16)
:NetRouting:OpenFh, CloseAtTermination :SrpRouting:NoRouting
Listing 8-8. Sample Request Definition File
The Structure of a Request
Each request in the request definition file is defined by a set of fields.
Each field is identified by a field name, which is enclosed in colons. The contents of the field follows the field name, on the same line. The field names themselves are keywords recognized by the Make Request Set utility. Each request definition contains the fields described in Table 8-6.
Table 8-6. Request Definition Fields
(Page 1 of 2)
Field
:RequestCode:
: RequestName:
:Version:
Description
This field marks the start of the definition of a request. The value in this field is the request code number.
Declares the name of the request, for documentation purposes. If the request has a procedural interface, the procedural name should be entered in this field. The procedural name is not read by the operating system.
Defines the version number of the request (default
= 0). This field controls the merging of request files. If two requests have the same request code, the one with the lower version number will be overwritten.
8-32 eTaS/Open Programming Practices and Standards - Part I
Table 8-6. Request Definition Fields QueryRequestlnfo. This allows you to verify that no other service has usurped your request code.
Defines the exchange to which the request is routed before the first ServeRq operation for that request. This field can have either of two values:
ExchlnstaliedMastr indicates that the request should be routed to the master if the service is not installed locally.
ExchlnstaliedLocal indicates that the request should not be routed, and status code 33 should
Defines the request procedural interface for the request. This field is used by the operating system for validation of request blocks. A fuller discussion of this field can be found later in this chapter.
Describes how the request should be routed in a networked environment. This field is described in more detail later in this chapter.
Describes how requests are routed between processor boards on the Shared Resource Processor (SRP). This field is described in more detail later in this chapter.
Writing Request-Based System Services 8-33
System requests must be identified to the operating system, as well as defined. System requests should be identified at the beginning of the request definition file, then defined in the body of the file with the other requests. To identify a system request, you must enter the desired request code in the data field of the appropriate request definition directive. For example, :WsAbortRq:OEFOSh.
Table 8-7 describes the system request directives.
Table 8-7. System Request Definition Directives
Directive
:WsAbortRq:
:TerminationRq:
:SwappingRq:
Description
Identifies the request code for an abort request.
Identifies the request code for a termination request.
Identifies the request code for a swapping request.
Defining the Procedural Interface
The :Params: field of each request definition defines the parameters for the procedural interface to the request. It contains one or more directives, each of which tells the operating system the size of one parameter, and that parameter's location in the request block. The parameters should be defined in the same order as they appear in the procedural interface.
When a client calls a system service via a procedural interface, it first pushes any required parameters onto the stack, then calls the procedure name. This passes control to the operating system, which builds a request block using the parameters pushed by the client. The operating system uses the information in the :Params: field to determine the size of each parameter, and its location in the request block. It then pops each parameter off of the stack, and copies it to the appropriate place in the request block.
8-34 eTOS/Open Programming Practices and Standards - Part I
The operating system has no way to check for correct use or number of parameters. The programmer who defines the procedural interface must make sure that valid parameters of the correct size are pushed in the correct order, or the request block the operating system creates will contain garbage.
The directives available for the :Params: field of the request definition are described in Table 8-8. Each :Params: field usually contains multiple directives, separated by commas. Note that there are five basic directives and five compound directives. The compound directives are most useful when sCntInfo is six.
Defining Request Routing
You must define two types of routing for each request: Network Routing, and SRP Routing. The :NetRouting: field defines how a request should be routed in a networked environment. The :SrpRouting: field defines how a request should be between processors on an SRP. Neither field affects routing across the local cluster.
The :NetRouting: field can contain multiple directives, separated by commas. The network routing directives are described in Table 8-9.
The :SrpRouting: field can contain only one directive. The SRP routing directives are described in Table 8-10.
Writing Request-Based System Services 8-35
Table 8-8. Request Procedural Interface Parameter Directives
Directive Description
none Indicates that there are no parameters for this procedural interface.
w(x) The word at the top of the stack should be moved to offset x in the request block.
b(x) The byte at the top of the stack should be moved to offset x in the request block. Note that while only a single byte is placed in the request block, a full word is popped from the stack.
p(x) The double-word (pointer) at the top of the stack should be moved to offset x in the request block.
c(v, x) The constant value v should be placed at offset x of the request block. No parameter is popped from the stack.
Ita Equivalent to w(16), w(14). This directive specifies that the logical file address, which is stored in the second and third words of control information, is currently at the top of the stack.
pbcbO Equivalent to p(18), w(22). This directive specifies that two parameters, a pointer and a word, should be popped from the stack and moved to locations 18 and 22 in the request block.
pbcb1 Equivalent to p(24), w(28). This directive specifies that two parameters, a pointer and a word, should be popped from the stack and moved to locations 24 and 28 in the request block.
pbcb2 Equivalent to p(30), w(34). This directive specifies that two parameters, a pointer and a word, should be popped from the stack and moved to locations 30 and 34 in the request block.
pbcb3 Equivalent to p(36), w(40). This directive specifies that two parameters, a pointer and a word, should be popped from the stack and moved to locations 36 and 40 in the request block.
8-36 eTOS/Open Programming Practices and Standards - Part I
Table 8-9. Request Network Routing Directives
FileSpec2 Routing is identical to FileSpec. This directive tells the operating system that there is a second file name in the request block, which may need default path insertion.
FileSpecP2S2 This request should be routed according to the file specification pointed to by the second pbcb pair in default path in one or more file specifications.
SpecPW Indicates that the default password may need to be inserted. When used with file, directory, or device routing, each name pbcb is assumed to have a pbcb immediately following it which points to a password. Otherwise, the first pbcb in the request block is assumed to point to a password.
Writing Request-Based System Services 8-37
Table 8-9. Request Network Routing Directives (Page 2 of 2)
Directive Description
RW This is a read or write request and may be piecemealed. This code should be used only if the request conforms to the required format for piecemealable requests.
OpenFh Indicates a connection-opening request. The resource handle should be returned in the first response pbcb in the request block.
CloseAtTermination This directive should be used with the OpenFh directive. It indicates that the new connection is non-permanent and should be closed if the client terminates. If this directive is not included in an OpenFh request, the connection remains open after the client terminates.
CloseFh Indicates a connection-closing request, and tells the operating system that the corresponding file handle should be released. The rFh directive should also be included for connection-closing requests.
Table 8-10. Request SRP Routing Directives (Page 1 of 2)
Directive Description
NoRouting SRP routing is unspecified. The operating system defaults to rRemote.
rLocal Indicates that the request should be served on the same processor.
rRemote The request is served locally if possible, else it is routed according to the SRP request routing table.
8-38 eTaS/Open Programming Practices and Standards - Part I
Table 8-10. Request SRP Routing Directives (Page 2 of 2)
Directive Description
rHandle The request is routed by file handle. Routing is similar to network routing by handle, but the mechanism applies only to file system requests.
NOTE: This routing scheme requires special handles. See your operating system documentation for details.
rFileld The low-order byte of the handle identifies the processor to which the request should be routed.
NOTE: This routing scheme requires special handles. See your operating system documentation for details.
rLineNumber Route to the processor which owns the cluster line specified in the handle. NOTE: This routing scheme requires special handles. See your operating system documentation for details.
rDevice Route the request by handle or by file specification to the processor specified by the routing name.
The routing name serves as a key to look up the target processor in the Master FP Name Table.
Making a Loadable Request Set
After the requests have been defined in a request definition file, they must be merged with the operating system on which the service or. its client will run. Software products that use requests should merge those requests as part of their installation script when they are first installed on a user's hard disk.
Before the requests can be merged, they must be converted to binary form, using the Make Request Set utility.
After the requests have been converted to binary form, they can be merged with the operating system, using the Install New Request utility.
For more information about these utilities, see your operating system documentation.
Writing Request-Based System Services 8-39
Making a Request Label Object File
Finally, to allow the client application to call the request procedural interface by its symbolic name, you must create an object file that defines the name, and link that file with the client application.
Most implementations of eTaS/Open provide an Assembler macro,
%RqName, which aids in defining request labels. This macro is generally located in the file RqLabl.mdf. See your operating system documentation for more information. Listing 8-9 shows an example of arequest label file for a system service.
; request labels for the requests in FooServerRq.c
; FooServerRqLabel.asm
$INCLUDE([Sys]<Sys}RqLabl.mdf)
% RqName( OEFOOh, "GetFooText")
% RqName( OEFOlh, "DeinstallFooServer")
%RqName( OEF02h, "OpenFooServer")
% RqName( OEF03h, "CloseFooServer")
Listing 8-9. Sample Request Label File
8-40 eTaS/Open Programming Practices and Standards - Part I