The four accounting system function calls enable developers to create servers that can charge for their services. For example, a database server can charge for the number of records viewed, the number of requests serviced, or the amount of connect time. A print server can charge for the number of pages printed.
Before reading this introduction, the developer must be familiar with the terms object name, object type, object ID, property type, and property value. For definitions of these terms, see the introduction to the Bindery Services chapter.
The following scenario illustrates the use of accounting system calls. File server FS1 is one of many file servers on an internetwork. FS1's bindery includes several objects (with various properties) including the following:
| Object Name | Object Type | Object ID | Properties |
| FS1 | FILE_SERVER | 00030011h | ACCOUNT_SERVERS... |
| BILL | USER | 00060025h | ACCOUNT_BALANCE
ACCOUNT_HOLDS... |
| PSERVER | PRINT_SERVER | 5C2701F1h | ... |
PSERVER is a print server that advertises its services on the internetwork and appears in FS1's bindery as a dynamic object.
The supervisor of FS1 has declared PSERVER as an accounting server by adding PSERVER's object ID to the 128-byte value segment associated with FS1's ACCOUNT_SERVERS property. Consequently, whenever an object in FS1's bindery uses PSERVER to print pages, PSERVER can charge the object (usually a user) for the service.
A user at workstation WS1 logs in to FS1 as BILL. BILL's ACCOUNT_BALANCE property has the following 128-byte value segment associated with it:
Offset Content Type 0 Balance byte [4] 4 Credit Limit byte [4] 8 Reserved byte [120]
The Balance field specifies the amount of money that BILL can use to purchase services on the internetwork. The internetwork administrator must choose which monetary unit to use. In this case, each unit equals one cent, so BILL's account balance equals $50.00 (1388h).
The Credit Limit field specifies a fraction of the balance. If the balance falls below the credit limit, BILL can no longer purchase services on the internetwork.
BILL's ACCOUNT_HOLDS property has the following 128-byte value segment associated with it:
Offset Content Type 0 HoldingServer1 Object ID byte [4] 4 HoldingServer1 Amount byte [4] ... 120 HoldingServer16 Object ID byte [4] 124 HoldingServer16 Amount byte [4]
Each Holding Server Object ID field specifies the object ID of an accounting server that is about to do some service for BILL.
Each Holding Server Amount field specifies the estimated charge for the service. FS1 actually subtracts this amount from BILL's account balance temporarily. No more than 16 accounting servers can appear in ACCOUNT_HOLDS at one time.
If BILL makes a request to queue a 10-page file for printing on print server PSERVER,
| v2.x | v3.x | v4.x | v5.x |
Request
Offset Content Type (request header) 6 FunctionCode (23) byte 7 SubFuncStrucLen * word (Hi-Lo) 9 SubFunctionCode (150) byte 10 ClientType word (Hi-Lo) 12 ClientNameLen byte 13 ClientName byte[ClientNameLen]
* SubFuncStrucLen = 4 + ClientNameLen
Reply
Offset Content Type (reply header) 8 AccountBalance long (Hi-Lo) 12 CreditLimit long (Hi-Lo) 16 Reserved byte[120] 136 HolderID1 long (Hi-Lo) 140 HoldAmount1 long (Hi-Lo) . . . . . . 256 HolderID16 long (Hi-Lo) 260 HoldAmount16 long (Hi-Lo)
Completion Code
0 0x00 Successful 150 0x96 Server Out Of Memory 192 0xC0 No Account Privileges 193 0xC1 No Account Balance 196 0xC4 Account Disabled 232 0xE8 Write To Group 234 0xEA No Such Member 235 0xEB Property Not Set Property 236 0xEC No Such Set 252 0xFC No Such Object 254 0xFE Directory Locked 255 0xFF Hard Failure
Remarks
This call allows a server to get an account status at the time of the request. No audit record is generated. The fields in the reply are the same as those described for the ACCOUNT_BALANCE and ACCOUNT_HOLDS properties. Refer to the introduction at the beginning of this chapter.
If the requesting server's object ID is not listed in the ACCOUNT_SERVERS property of the file server's object, the No Account Privileges (192) completion code is returned. If the requesting (user) object has no ACCOUNT_BALANCE property, the No Account Balance (193) completion code is returned. Other errors are shown in the Completion Code section.
| v2.x | v3.x | v4.x | v5.x |
Request
Offset Content Type (request header) 6 FunctionCode (23) byte 7 SubFuncStrucLen * word (Hi-Lo) 9 SubFunctionCode (151) byte 10 ServiceType word (Hi-Lo) 12 ChargeAmount long (Hi-Lo) 16 HoldCancelAmount long (Hi-Lo) 20 ClientType word (Hi-Lo) 22 CommentType word (Hi-Lo) 24 ClientNameLen byte 25 ClientName byte[ClientNameLen] 25+ClientNameLen CommentLen byte 26+ClientNameLen Comment byte[CommentLen]
* SubFuncStrucLen = 17 + ClientNameLen + CommentLen
Reply
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 1 0x01 Out Of Disk Space 136 0x88 Invalid File Handle 148 0x94 No Write Privileges 150 0x96 Server Out Of Memory 162 0xA2 I/O Lock Error 192 0xC0 No Account Privileges 193 0xC1 No Account Balance 194 0xC2 Credit Limit Exceeded 196 0xC4 Account Disabled 232 0xE8 Write To Group 234 0xEA No Such Member 235 0xEB Property Not Set Property 236 0xEC No Such Set 254 0xFE Directory Locked 255 0xFF Hard Failure
Remarks
This call allows a server to submit a charge to an account. The charge is subtracted from the object's account balance, and an audit record is generated. The Hold Cancel Amount is the same as the amount specified in the previous corresponding Submit Account Hold call. If no Submit Account Hold call was made prior to providing the service, the Hold Cancel Amount is zero. A Hold Cancel Amount of zero has no effect on other outstanding holds by the server.
If the requesting server is not listed in the ACCOUNT_SERVERS property of the file server's object, the No Account Privileges (192) completion code is returned. If the object specified has no ACCOUNT_BALANCE property, the No Account Balance (193) completion code is returned. In either case, the account is not charged even though an entry is recorded in the audit file. If the object's balance falls below its lowest permissible limit, the Credit Limit Exceeded (194) completion code is returned.
An audit record is generated when a charge is submitted and the ACCOUNT_SERVERS property of the file server object exists. This record is generated even if an non-zero completion code is returned by the Submit Account Charge call.
| v2.x | v3.x | v4.x | v5.x |
Request
Offset Content Type (request header) 6 FunctionCode (23) byte 7 SubFuncStrucLen * word (Hi-Lo) 9 SubFunctionCode (152) byte 10 Amount long (Hi-Lo) 14 ClientType word (Hi-Lo) 16 ClientNameLen byte 17 ClientName byte[ClientNameLen]
* SubFuncStrucLen = 8 + ClientNameLen
Reply
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 1 0x01 Out Of Disk Space 136 0x88 Invalid File Handle 148 0x94 No Write Privileges 150 0x96 Server Out Of Memory 162 0xA2 I/O Lock Error 192 0xC0 No Account Privileges 193 0xC1 No Account Balance 194 0xC2 Credit Limit Exceeded 195 0xC3 Too Many Holds 196 0xC4 Account Disabled 232 0xE8 Write To Group 234 0xEA No Such Member 235 0xEB Property Not Set Property 236 0xEC No Such Set 252 0xFC No Such Object 254 0xFE Directory Locked 255 0xFF Hard Failure
Remarks
This call allows a server to hold an amount, pending a subsequent charge to the client's account. The amount, along with the requesting server's object ID, is recorded in the object's ACCOUNT_HOLDS property. If the requesting server has an outstanding hold, the new hold amount is added to that server's outstanding hold amount.
A server can back out a hold (in the event that the service is not provided) by calling Submit Account Hold with the additive inverse of the amount originally held. A server can also choose to partially back out a hold by submitting a smaller negative amount. To clear all holds, a server can submit a hold with a the amount set to 0 (zero).
If service is provided, the hold should be cleared by specifying the original hold amount plus the charge amount in the Submit Account Charge request.
If the requesting server's object ID is not listed in the ACCOUNT_SERVERS property of the file server's object, the No Account Privileges (192) completion code is returned. If the object specified does not have an ACCOUNT_BALANCE property, the No Account Balance (193) completion code is returned. If the current balance minus all holds (including the requested hold) is less than the permissible amount, the call fails, and the Credit Limit Exceeded (194) completion code is returned. If too many other servers (16) have outstanding holds on the user's account, the call fails, and the Too Many Holds (195) completion code is returned.
| v2.x | v3.x | v4.x | v5.x |
Request
Offset Content Type (request header) 6 FunctionCode (23) byte 7 SubFuncStrucLen * word (Hi-Lo) 9 SubFunctionCode (153) byte 10 ServiceType word (Hi-Lo) 12 ClientType word (Hi-Lo) 14 CommentType word (Hi-Lo) 16 ClientNameLen byte 17 ClientName byte[ClientNameLen] 17+ClientNameLen CommentLen byte 18+ClientNameLen Comment byte[CommentLen]
* SubFuncStrucLen = 9 + ClientNameLen + CommentLen
Reply
Offset Content Type (reply header)
Completion Code
0 0x00 Successful 1 0x01 Out Of Disk Space 150 0x96 Server Out Of Memory 192 0xC0 No Account Privileges 193 0xC1 No Account Balance 196 0xC4 Account Disabled 232 0xE8 Write To Group 234 0xEA No Such Member 235 0xEB Property Not Set Property 236 0xEC No Such Set 240 0xF0 Illegal Wildcard 252 0xFC No Such Object 255 0xFF Hard Failure
Remarks
This call allows a server to record a note about a client's account activities in the audit file. For example, the file server uses this call to record a login time.
If the requesting server is not listed in the ACCOUNT_SERVERS property of the file server's object, the No Account Privileges (192) completion code is returned. In this case, no audit record is generated.