|
|
|
Use the $SERVER() function to provide linkage to server IMODs. It also provides services to the server IMODs themselves, permitting easy implementation of the server IMOD conventions.
The $SERVER() function has this syntax:
Form 1:
x = $SERVER(REQUEST,service,[arg],[control])
Form 2:
$SERVER(action,service,imod,[desc])
Form 3:
$SERVER(command,service,[option])
Form 4:
$SERVER(INTERNAL,[service],subcmd,[reqimid,reqstk],[retstk],[string])
The $SERVER() function takes these arguments:
Result string from the server IMOD.
Queues a request for execution by a server IMOD.
Name of the service to be invoked.
Argument string to be passed to the server IMOD. The content of this string depends on the service being requested.
Control option. Specify one of the following:
Returns control after the request is processed.
Queues the request and returns control immediately to the requestor.
Action to be taken. Specify one of the following:
Defines or redefines a new server IMOD to the system.
Deletes an existing server IMOD definition. Deleting an operating server IMOD does not affect it in any way, except that its existence becomes unknown to the system for any future requests or commands.
Name of the IMOD that is to be invoked to start the named server.
Description of the service. This description is made available for reports and displays.
Command to be issued to the server IMOD. This may be one of the predefined server commands that are listed in "Server Commands" or another command that is specifically supported by the server.
Modifiers that affect how a command is executed by the server IMOD. The options are listed with the server commands in the following section.
Indicates that the request deals with the internal operation of a server IMOD. INTERNAL requests are only made from within a server IMOD and provide a convenient mechanism for providing standard services.
Tailors the INTERNAL service by the specification of subcommands that are listed in "INTERNAL Subcommands".
IMOD ID of the IMOD task that originated a request.
Stack number, where results of a request are to be returned.
Stack number that contains stack records to return. Default: Current stack.
String of data to be returned to the requesting IMOD task.
In addition to REQUEST, DEFINE and DELETE, a series of commands have been defined for operating server IMODs. The following is a list of the available commands, their effects, and options:
|
CANCEL |
Cancels the server IMOD. This command should be avoided since the current request (and all queued requests) are abandoned and the requesting IMODs are not notified. |
|
CYCLE |
Cancels the current server IMOD and starts a new server. Queued requests are transferred to the new server. |
|
DEQUEUE |
Transfers all queued requests to the current stack of the IMOD task issuing the command. |
|
DISPLAY |
Returns information on all currently defined servers on the stack. The first character of each stack record serves as a delimiter character. The fields returned, in order, are Service, IMOD name, IMOD task ID (if running), and Description. |
|
HOLD |
Continues to permit requests to be queued, but does not permit processing of any requests from the queue. |
|
PAUSE |
Prevents acceptance of any further requests for queuing. Processing of already queued requests is deferred. |
|
PURGE |
Fails each request in the current request stack and notifies any waiting requestors of the failure. |
|
QUIESCE |
Prevents queuing of additional requests, but permits processing of any requests that have already been queued. |
|
RESET |
Deletes all unprocessed requests. No processing is performed and the requestors are not notified. |
|
RESUME |
Cancels the effects of any outstanding HOLD, PAUSE, or QUIESCE. |
|
START |
Starts the named service. Any specified options are passed to the server IMOD in the argument string, following the service name. |
|
STATUS |
Returns the status of a particular server IMOD on the stack. The information returned is formatted for display purposes. |
|
STOP |
Performs a QUIESCE function and then a TERMINATE function when all queued requests have been completed. |
|
TERMINATE |
Terminates processing immediately. Ignores any unprocessed requests. |
|
TEST |
Returns the current status of the server as the result. Values are UNDEFINED, STOPPED, STOPPING, PAUSED, HOLDING, QUIESCED, and AVAILABLE. |
The INTERNAL service is used only from within a server IMOD. It permits easy implementation of server IMOD conventions and standardized coding. The following lists each available subcommand and any modifiers that are appropriate. For a detailed discussion and examples of writing server IMODs, see the server IMOD information in the Administration Guide.
|
AUTO |
Intercepts all COMMAND functions and handles them without the knowledge of the server. The interception and execution are performed whenever the WAIT subcommand is issued. The effect of AUTO can be canceled with the NOAUTO subcommand. |
|
COMPLETE |
Posts a request as complete and returns the results to the requesting IMOD. This option requires specification of reqimod and reqstk. You can use string to return a result string. |
|
HOLD |
Prevents the processing of any additional requests. Requests continue to be queued. Commands continue to be processed. |
|
NOAUTO |
Cancels a previously issued AUTO subcommand. |
|
PAUSE |
Prevents queuing of additional requests. Processing of any already queued requests is deferred. |
|
PURGE |
Fails each request in current request stack and notifies waiting requestors. If string is specified, it is returned as the result. If omitted, the result will be: FAILED: REQUEST PURGED. |
|
QUIESCE |
Prevents further requests from being queued. The WAIT subcommand returns both commands and already queued requests. |
|
RESET |
Deletes all entries from the request stack. No processing is performed and waiting requestors are not notified. Extreme care should be used when using this option. |
|
RESUME |
Cancels the effects of any outstanding HOLD, PAUSE, or QUIESCE. |
|
SETUP |
Performs all functions necessary to establish a server IMOD. This service should be invoked once when the server IMOD task is first started. |
|
TERMINATE |
Terminates processing immediately. Any unprocessed requests are ignored and discarded. |
|
WAIT |
Waits for a command or request to be entered. The returned value is REQUEST (indicating that a request has been received), COMMAND (if a command is to be processed), TERMINATE (if immediate termination is to occur), or FAIL: text (if a failure has occurred). |
See the server IMOD information in the Administration Guide for additional information and examples of coding and using server IMODs.
The $SERVER() function returns a variety of result strings, depending on the request. All requests may return a result in the form: FAIL: text, where text is descriptive of the condition causing the failure.
In lieu of specific results, the string SUCCESS is returned to the caller.
| Copyright © 2011 CA. All rights reserved. | Tell Technical Publications how we can improve this information |